Reference
Troubleshooting
Identify whether a problem is sign-in, permissions, workspace access, assistant setup or the job itself.
No NetConverter tools in the assistant
- Run
netconverter --version,netconverter whoamiandnetconverter connecton the host that starts the bridge. - Check the configured workspace and executable path.
- Restart the assistant or OpenClaw Gateway after configuration changes.
- Check the client matrix for version and environment requirements.
Access denied or missing capabilities
mcp_not_granted or “MCP not enabled” needs an administrator to enable the correct account or organization. A 403 can also mean the credential does not allow the operation. Run netconverter capabilities; a pilot key is not a full-API credential.
A stored API key is used before a saved browser sign-in. Inspect whoami to ensure you are testing the intended identity. Do not copy a key into chat to diagnose this.
The Gateway cannot reach credentials
OpenClaw’s Gateway environment can differ from your interactive terminal. On Linux, the OS keyring may need DBUS_SESSION_BUS_ADDRESS. For encrypted file storage, the bridge needs the supported passphrase environment variable or passphrase-file setting. Use your host’s secret-management mechanism and avoid plaintext secrets in shared configuration.
A locked or missing keyring is different from an expired account token. Read the exact safe error and follow the credential-store guide.
Uploads are declined or ask for a confirm token
Some assistants (ChatGPT, Claude Code) cannot show the bridge’s confirmation form and answer it unseen. From CLI 0.7.0 the bridge then sends nothing and returns confirmation_required with a single-use token: the assistant must ask you in the chat, and retries with the token only after your yes. To rely on the assistant’s own tool approval instead, start the bridge with --no-upload-confirm. upload_declined means you declined or closed the form; invalid_confirm_token means the token was used, expired or belonged to another call.
Guided-migration or write tools are missing
The guided tools need the folder at exposure level full (netconverter privacy level full), then a restart of the assistant. write_tools_disabled means propose_operations, submit_conversion or apply_mapping_answers are not enabled for your tenant; an administrator enables them, or decide and convert in Conversion Studio or Quick Convert. Ask the assistant to call account: its guided_migration field names what is missing and why.
The hosted connector refuses the sign-in
oauth_client_not_enrolled means the app is not an accepted NetConverter client (self-registered apps are refused). Use the local bridge (netconverter login --clerk, then netconverter connect), or enter the NetConverter client ID RjSv1z2Gms6iS96s with no secret, or an API key with the mcp:tools scope. All codes: error codes and what to do.
File not found, too large or refused
Use a file inside the bridge’s chosen workspace, on the same host. Paths and symlinks escaping that workspace are refused. Check account limits for oversized input. For an unsupported source or target, choose a path the service advertises rather than renaming the file to force detection.
Names look like tokens
That is expected in strict/masked views. Inspect netconverter privacy status. Increasing exposure is a separate user choice, not a prerequisite for fixing every connection issue.
The job needs review or a download failed
NEEDS REVIEW and BLOCKED are results to inspect, not generic connection errors. Read their reasons. A hash mismatch or a different existing output should be investigated; do not overwrite the original to hide the mismatch. Resume with the real job ID if the workflow was interrupted.
Get help with useful evidence
Share the CLI version, assistant version, OS, operation, safe error text and job ID through your approved support channel. Remove credentials and customer data. Contact NetConverter for access or workflow help.
Source and release context: Troubleshooting reference · Gateway environment