Troubleshooting
Common problems, error messages, and their solutions. If you cannot find your issue here, contact support@clevername.net with as much detail as possible.
Key Concepts
Before you troubleshoot
- Check clevername.net to confirm the site is reachable.
- Clear your browser cache and try a hard refresh (
Ctrl+Shift+RorCmd+Shift+R). - Check that you are on the latest version by reloading the page.
- Open browser developer tools (F12) and check the Console tab for error messages.
API Key Issues
SYMPTOM"No models available" in the chat model selector
CAUSENo valid API key is configured for any provider.
FIXGo to Settings > Keys and add an API key for Anthropic, OpenAI, or Google. The key must be valid and have a positive balance with the provider.
SYMPTOM"Invalid API key" error when chatting
CAUSEThe API key stored for the selected provider has been revoked, expired, or was entered incorrectly.
FIXGo to Settings > Keys, delete the existing key, and re-enter a valid key from your provider's dashboard (console.anthropic.com, platform.openai.com, or aistudio.google.com).
SYMPTOM"Insufficient funds" or "Quota exceeded" error from provider
CAUSEYour provider account has run out of prepaid balance or hit a rate limit.
FIXAdd funds or increase your rate limit on the provider's platform (console.anthropic.com, platform.openai.com, or aistudio.google.com). Clevername passes through provider errors with no markup.
SYMPTOMMFA prompt keeps appearing when managing keys
CAUSEMFA verification is required for every key management operation (add, update, delete). This is a security requirement.
FIXComplete the MFA challenge. If your authenticator app is not working, check that your device clock is synchronized (TOTP codes are time-sensitive).
SYMPTOM"Provider grayed out" in the model selector
CAUSEA valid API key for that provider is not configured.
FIXGo to Settings > Keys to add a key for the grayed-out provider.
Connection Problems
SYMPTOMMCP server shows "disconnected" status
CAUSEThe remote MCP server is unreachable or has changed its endpoint.
FIXClick the Ping button on the connection to test reachability. If it fails, verify the server URL and check that the server is running. For integration directory servers, the issue may be temporary.
SYMPTOMIDE gateway shows no tools after connecting
CAUSEThe OAuth login may not have completed, or no MCP servers are activated in your account.
FIX1. Confirm you completed the browser sign-in prompt. 2. Go to the dashboard and verify you have at least one MCP server installed/connected. 3. Restart your IDE to refresh the tool list.
SYMPTOM"Timeout" errors when using MCP tools in chat
CAUSEThe MCP server took too long to respond. Some servers have cold-start latency.
FIXTry the request again. If it persists, the server may be overloaded or down. Check the server's health status in the Connections tab.
SYMPTOM"CORS error" in browser console
CAUSEA browser extension or network proxy is interfering with requests to clevername.net.
FIXDisable browser extensions one by one to identify the culprit. Ad blockers and privacy extensions are common causes.
Authentication Issues
SYMPTOMRedirected to login page repeatedly
CAUSEYour session has expired or cookies are being blocked.
FIX1. Clear cookies for clevername.net. 2. Ensure third-party cookies are allowed for supabase.co (required for auth). 3. Log in again.
SYMPTOM"Unauthorized" (401) error on API calls
CAUSEYour session token has expired, or the API key/gateway token is invalid.
FIXRefresh the page to get a new session token. For API integrations, verify your Authorization header is correct and the token has not been revoked.
SYMPTOMMFA setup fails with "Invalid code"
CAUSEThe TOTP code is time-sensitive. If your device clock is out of sync, codes will not match.
FIXEnsure your device has automatic time sync enabled (NTP). Try entering the code immediately after it refreshes in your authenticator app.
SYMPTOMCannot log in after password reset
CAUSEThe password reset link may have expired (links are valid for 1 hour).
FIXRequest a new password reset from the login page. Check spam/junk for the email. Use the link within 1 hour.
SYMPTOMSSO login redirects to an error page
CAUSEThe SSO configuration (SAML/OIDC) may have incorrect ACS URL, entity ID, or certificate.
FIXContact your org admin to verify the SSO settings match the values shown in the Clevername org settings. See the SSO Setup guide for details.
Rate Limiting
SYMPTOM"429 Too Many Requests" error
CAUSEYou have exceeded the rate limit for the endpoint.
FIXWait a few seconds and retry. Rate limits are per-endpoint and reset automatically. If you are building an integration, implement exponential backoff.
SYMPTOM"Budget exceeded" error on gateway calls
CAUSEThe agent's per-session or per-month budget has been exhausted.
FIXEnd the current session and create a new one with a higher budget, or wait for the monthly budget to reset. Organization admins can adjust agent budgets.
SYMPTOMAgent trust score dropped to "Restricted" tier
CAUSERepeated policy violations (scanner findings, tool drift, budget overruns) have reduced the trust score.
FIXReview the agent's recent activity in the SOC Console to identify the violations. Fix the underlying issues (update the agent's config, adjust its tools, etc.) and the score will recover over time.
Gateway Token Issues
SYMPTOM"Invalid or expired gateway token" (401) on gateway calls
CAUSEThe cnk_* token was revoked, expired, or entered incorrectly.
FIXCreate or rotate the agent's gateway token in Dashboard -> API Keys and update your agent's configuration with the new token.
SYMPTOM"Agent not found" (404) when starting a session
CAUSEThe agent_id does not exist or belongs to a different user.
FIXVerify the agent_id from the registration response. Agent IDs are UUID format.
SYMPTOMContent scan returns findings for safe content
CAUSECleverGuard may flag content that contains patterns similar to PII or injection attempts (false positive).
FIXReview the specific flags in the scan response. If they are false positives, adjust the agent's guardrail profile to lower the scanner sensitivity for that category.
SYMPTOM"Tool not in allowed list" when calling check-tool
CAUSEThe tool is not in the agent's allowed_tools list or integration bindings.
FIXUpdate the agent's registration to include the tool in allowed_tools, or submit the agent for Re-review with updated bindings.
Error Code Reference
Clevername uses standard HTTP status codes plus custom error codes for governance-specific scenarios. The table below covers every error you may encounter, what causes it, and how to resolve it.
HTTP Status Codes
| Code | Name | Common Causes | How to Resolve |
|---|---|---|---|
| 400 | Bad Request | Missing required fields, invalid UUID, malformed JSON, invalid model name. | Check the request body against the API documentation. Read the detail field in the error response for the specific validation failure. |
| 401 | Unauthorized | Missing or invalid Authorization header, expired JWT, revoked cnk_* token. | Refresh your browser session (re-login). For API integrations, verify the token has not been revoked. Rotate the token if needed via the dashboard. |
| 402 | Budget Exceeded | Per-session budget or monthly agent budget has been exhausted. | End the current session and create a new one with a higher budget. For monthly limits, wait for the reset or have an org admin increase the agent's monthly budget. |
| 403 | Forbidden | Agent not approved by Agent Review. Role insufficient. Model drift (agent tried to use an unapproved model). Guardrail profile restriction. | Check the error detail. If review approval is required, submit the agent for review. If model drift, update the agent's approved model list. If role-based, contact your org admin. |
| 404 | Not Found | Agent ID, session ID, or resource does not exist or belongs to a different user. | Verify the ID from the original creation response. Agent and session IDs are UUID format. |
| 429 | Rate Limited | Too many requests to the same endpoint. Scan endpoint has tighter limits (100/min). FP disputes: 5/hour. | Wait and retry with exponential backoff. If building an integration, implement jitter. The Retry-After header indicates when to retry. |
| 503 | Service Unavailable | Hub Core is temporarily unavailable (deployment in progress, cold start). | Wait 10-30 seconds and retry. If persistent, check the Clevername status page or contact support. |
Governance Error Codes
These codes are specific to Clevername's governance engine and appear in tool call responses or as part of the error body.
| Code | Name | What Happened | How to Resolve |
|---|---|---|---|
| -32403 | Tool Drift Blocked | The agent tried to call a tool that is not in its approved allowed_tools list or integration bindings. | Update the agent's registration to include the tool in allowed_tools. If the Agent Review is enabled, resubmit the agent for review with updated bindings. |
| -32404 | Pending Approval | The action matched a high-risk pattern in the guardrail profile (A4 autonomy question). A SignedApproval push request was created automatically. | Wait for the approval to be granted via the SignedApproval app. The response includes a request_id you can poll. Alternatively, adjust the guardrail profile to reclassify the action. |
| scanner_block | Content Blocked | CleverGuard detected a policy violation in the input or output: prompt injection, PII, secrets, or URL blocking. | Review the findings array in the error response. If it is a false positive, submit a dispute at /v1/guard/disputes. Otherwise, adjust the content to comply with the guardrail profile. |
Getting Help
If you cannot resolve your issue with the information above:
Email Support
support@clevername.netInclude your account email, the error message (exact text), and steps to reproduce.Help Center
clevername.net/helpSearch the help center for feature-specific guides and FAQs.Tip
When contacting support, include: your account email, the exact error message or screenshot, the browser/IDE you are using, and the steps to reproduce the issue. This helps us resolve your issue faster.