Troubleshooting
Common issues and solutions.
Connection Issues
OAuth authentication error
If your AI shows an authentication error when connecting, make sure you're logging in with the same email associated with your Titan Tools account. Try disconnecting and re-adding the MCP server to start a fresh OAuth flow.
Connection refused or timeout
Make sure the server URL is correct. For Custom Connector users, verify you're using the full URL including /api/mcp. For API key users, verify your key hasn't been revoked.
"Unauthorized" error (401)
Your API key may be invalid or expired. For Claude Code users, re-run the install command. For OpenClaw users, check your configured key with: openclaw config get plugins.entries.titan-connect.config.TITAN_API_KEY
Data Issues
Data tools returning "no seller selected"
Before using data tools, you need to set an active seller. Ask your AI to "list my seller accounts" and then "set [store name] as active".
All zeros returned
This usually means one of three things: (1) wrong currency code — use the seller's mainCurrency (USD, GBP, EUR, etc.), (2) end date is too recent — Amazon data lags by ~2 days, or (3) the date range is too narrow.
Wrong date range
Always use YYYY-MM-DD format. Set the end date to today minus 2 days. Default to the last 30 days unless otherwise specified.
Platform-Specific
Custom Connector not showing tools
After adding the MCP server URL and authenticating, your AI should automatically discover all 28 tools. If tools don't appear, try removing and re-adding the connector. Make sure your Titan Tools account has an active subscription.
Claude Code plugin not loading
Run source ~/.zshrc (macOS) or source ~/.bashrc(Linux) to reload the plugin. If that doesn't work, re-run the install command.
OpenClaw plugin not in plugins list
Run openclaw plugins list to check if the plugin is installed. If not, re-run the install command. Make sure OpenClaw is up to date.
Error Recovery Quick Reference
| Error | Fix |
|---|---|
| No active seller | Call set_active_seller first |
| All zeros returned | Check currencyCode, endDate (today-2), and date range width |
| Multiple stores same name | Pass marketplace param to disambiguate |
| Empty results | Try broader date range or different search terms |
| Rate limited (429) | Wait 60 seconds and retry |
| Tool not available (403) | API key may lack data tools access — use knowledge tools instead |
| 401 Unauthorized | Invalid or expired API key |
| Account tools missing | Account tools require OAuth (custom connector or Claude Code). tk_* keys cannot use them. |
| Cannot delete default account | Default (isPrimary) accounts are protected. Delete a different one, or replace via the dashboard. |
| Data tool fails after switch_account | Switching resets the active seller. Re-run list_seller_accounts + set_active_seller. |
Action Tools (propose_*)
| Result | Meaning / fix |
|---|---|
MUST_SET_ACTIVE_ACCOUNT | No Titan Tools account active — call list_accounts then switch_account |
NO_ACTIVE_SELLER | No seller selected — call list_seller_accounts then set_active_seller |
OAUTH_REFRESH_FAILED | TitanTools refresh token rotated/expired — reconnect at titanconnect.titannetwork.com |
INSUFFICIENT_SCOPE | OAuth scope tools:write (or mcp) is required. tk_* API keys never grant action access. |
NEXUS_CALL_FAILED | Nexus 5xx or transport error — surface the error message; do NOT retry without LIST-ing first to verify state |
Partial multi-status (error.length > 0) | Some items succeeded, some failed. Narrate per-item to the user. |
| Action tools not visible | Authenticate via OAuth (custom connector / Claude Code OAuth login) with tools:write scope. Plan grant must include action category when billing is enabled. |
All action results show dryRun: true | This is the default — actions are simulated, not executed on Amazon. Operator must flip ACTIONS_FORCE_DRY_RUN=false per the runbook. |