Troubleshooting

Common issues and direct fixes

Provider status meanings

• Ready: provider installed and latest checks passed.
• Needs auth: required credential missing, expired, or revoked.
• Verification failed: endpoint reachable but runtime checks failed.
• Blocked: policy/readiness state prevents active use.

Connection setup issues

• OAuth completed but provider is not in Library: treat that as install failure. Retry connect from Catalog; the provider should only appear after verification succeeds.
• npx says no clients detected: install/update local client first, then rerun npx loadoutz@latest connect <setup-url>.
• What “no clients detected” means: CLI could not find supported config targets on this machine, so it did not auto-write files.
• Claude Desktop not added by npx: expected; finish in Settings -> Connectors with same setup URL.
• Claude Code command fails: update Claude CLI, rerun npx, then use direct claude mcp add ... fallback if needed.
• ChatGPT Web not accepting setup yet: currently experimental/coming soon on this deploy; use Codex/VS Code/OpenCode/Claude clients.
• After rerunning npx, still stale: restart client process so it reloads MCP config.

Runtime issues

• invalid_token: reconnect OAuth for the owner route URL, then rerun initialize and tools/list.
• Tool missing in client: confirm tool is in active loadout, then rerun tools/list.
• Setup panel shows a red warning: fix the provider auth or loadout issue first, then copy setup URL again.
• 405 on GET: expected; use JSON-RPC over HTTP POST.
• New loadout added but update rejected: permission expansion can require re-consent; reconnect using owner URL and retry.
• -32602 from tool call: treat as input schema mismatch first; inspect required args and retry.

Custom import issues

• Invalid endpoint: endpoint must be public HTTPS with DNS hostname and MCP-compatible path.
• Auth required during verification: endpoint likely requires headers/credentials; provide supported auth path (apiKey / pat).
• Custom OAuth blocked: use catalog OAuth provider flow; custom OAuth import is intentionally disabled.