Troubleshooting
Diagnose MCP discovery, workspace connectivity, policy rejection, and incomplete tool results.
Start at the local client, then follow the request toward the remote workspace. This keeps transport failures separate from workspace or policy failures.
The agent cannot see Jio
Check the MCP entry
Confirm the client is reading the expected configuration file and that the command path is absolute or resolvable in its launch environment.
Run the bridge directly
Start it from the same user account and environment as the agent. Look for missing files, permissions, or configuration.
Reload the client
Many MCP clients discover servers only at startup or after an explicit configuration reload.
Inspect protocol logs
Look for startup exits, malformed messages, version mismatches, or a server that writes diagnostics to the protocol stream.
The workspace is unavailable
| Symptom | Likely area | Check |
|---|---|---|
| Connection timeout | Network path | Routing, firewall, private address, service listener |
| Authentication rejected | Identity | Credential source, expiry, workspace binding |
| Workspace not found | Configuration | Workspace name, host, and root mapping |
| Connection drops during commands | Capacity | Memory pressure, timeouts, service restarts |
An operation is rejected
A rejection may be correct. Read the policy reason before changing configuration.
- Confirm the resolved target is inside the intended workspace.
- Check whether the capability is disabled or merely requires approval.
- Verify the remote operating-system identity has the required permission.
- Compare resource or network usage with configured limits.
- Retry only after changing the request or the applicable policy.
Collect a diagnostic bundle
Include:
- Jio and client versions;
- the failing capability and a minimal reproduction;
- timestamps with timezone;
- bridge startup and transport errors;
- remote service health and recent restarts;
- the effective policy with secrets removed;
- exit status and whether output was truncated.
Sanitize before sharing
Diagnostic output can contain repository paths, source code, hostnames, tokens, or command arguments. Remove sensitive values before opening an issue.