Common Errors

Reference for error messages you may encounter when using Toolcog, organized by category.

Authentication Errors

authorization_required

{
  "error": "authorization_required",
  "message": "This operation requires authorization",
  "connect_url": "https://toolcog.com/connect?owner={owner}&bridge={bridge}&scope={scope}"
}

Cause: The operation requires credentials that aren’t available.

Resolution:

1. Click the connect_url to authorize the service
2. Complete the OAuth flow or enter API key
3. Retry the operation

invalid_credentials

{
  "error": "invalid_credentials",
  "message": "The provided credentials are invalid"
}

Cause: Stored credentials are rejected by the API.

Resolution:

1. Go to Settings → Connections
2. Revoke the affected connection
3. Reconnect with valid credentials

token_expired

{
  "error": "token_expired",
  "message": "OAuth token has expired"
}

Cause: OAuth access token expired and couldn’t be refreshed.

Resolution:

1. Go to Settings → Connections
2. Click Reconnect for the affected service
3. Complete the OAuth flow again

insufficient_scopes

{
  "error": "insufficient_scopes",
  "message": "Token lacks required scopes: repo, admin:org"
}

Cause: The OAuth token doesn’t have all scopes needed for this operation.

Resolution:

1. Go to Settings → Connections
2. Revoke the current connection
3. Reconnect and grant the additional scopes
4. Some operations require elevated permissions

credential_not_found

{
  "error": "credential_not_found",
  "message": "No credential found for scheme: bearerAuth"
}

Cause: The operation requires a security scheme that has no stored credential.

Resolution:

1. Check if you’ve connected the required service
2. If not, follow the authorization prompt
3. If connected, verify the scheme name matches

Discovery Errors

no_operations_found

No API operations found matching your intent. Try rephrasing your search.

Cause: Semantic search found no matches for your query.

Resolution:

• Rephrase to focus on behavior: “create a customer” instead of “stripe customer”
• Be more specific: “list all repositories for a user” instead of “get repos”
• Try different terminology
• Check that the API is included in your catalog

operation_not_found

Operation not found: stripe/invalid.operation

Cause: The exact operation name doesn’t exist.

Resolution:

1. Use find_api to discover the correct operation name
2. Check for typos in the operation identifier
3. Verify the API is included in your catalog

invalid_operation_format

Invalid operation format. Expected: serviceName/operationName

Cause: Operation identifier doesn’t follow the required format.

Resolution:

• Use format: serviceName/operationName
• Both segments must be non-empty
• Example: github/repos.create, not github or /repos.create

Execution Errors

request_encoding_failed

{
  "error": "request_encoding_failed",
  "message": "Failed to encode request: missing required parameter 'owner'"
}

Cause: Arguments don’t satisfy the operation’s requirements.

Resolution:

1. Use learn_api to see required parameters
2. Ensure all required fields are provided
3. Check parameter names match exactly (case-sensitive)

api_error_4xx

HTTP 4xx errors from the upstream API:

Resolution:

• Check the response body for specific error details
• Review parameters against API documentation
• For 429: wait and retry, or reduce request frequency

api_error_5xx

HTTP 5xx errors from the upstream API:

Resolution:

• These indicate problems with the upstream API
• Wait and retry
• Check the service’s status page

response_decoding_failed

{
  "error": "response_decoding_failed",
  "message": "Failed to parse API response"
}

Cause: The API returned an unexpected response format.

Resolution:

• This may indicate an API bug or version mismatch
• Check if the API has changed
• Report the issue if it persists

timeout

{
  "error": "timeout",
  "message": "Request timed out after 30s"
}

Cause: The API didn’t respond in time.

Resolution:

• Retry the request
• For large operations, check if the API supports pagination
• Some operations legitimately take longer

Configuration Errors

invalid_catalog_configuration

{
  "error": "invalid_catalog_configuration",
  "message": "Catalog has no sources configured"
}

Cause: The catalog is missing required configuration.

Resolution:

1. Navigate to your catalog
2. Go to Sources and add at least one source
3. Save the catalog

invalid_override_configuration

{
  "error": "invalid_override_configuration",
  "message": "OAuth override missing required field: tokenUrl"
}

Cause: An override is incomplete or invalid.

Resolution:

1. Navigate to your catalog → Overrides
2. Edit the flagged override
3. Provide all required fields
4. See Override Types for requirements

invalid_source_filter

{
  "error": "invalid_source_filter",
  "message": "Invalid filter pattern: [invalid"
}

Cause: Source filter pattern has syntax errors.

Resolution:

• Check filter syntax
• Valid patterns: repos/*, GET /users/*, payments-*
• Escape special characters if needed

realm_not_found

{
  "error": "realm_not_found",
  "message": "Realm not found: myorg/invalid-realm"
}

Cause: An override references a non-existent realm.

Resolution:

1. Create the realm in your organization
2. Or correct the realm reference in the override

Connection Errors

session_not_found

Session not found

Cause: MCP session is invalid or expired.

Resolution:

1. Restart your MCP client
2. Reconnect to the Toolcog server
3. Re-authenticate if prompted

mcp_connection_failed

{
  "error": "mcp_connection_failed",
  "message": "Failed to establish MCP connection"
}

Cause: Can’t connect to the MCP server.

Resolution:

1. Check your internet connection
2. Verify the MCP server URL is correct
3. Check if Toolcog services are operational
4. Review your MCP client configuration

session_expired

{
  "error": "session_expired",
  "message": "Session has expired, please reconnect"
}

Cause: Browser session or API key has expired.

Resolution:

1. Sign in again at toolcog.com
2. Or generate a new API key
3. Update your MCP client configuration if needed

rate_limited

{
  "error": "rate_limited",
  "message": "Too many requests, please slow down",
  "retry_after": 60
}

Cause: Exceeded Toolcog’s rate limits.

Resolution:

• Wait for retry_after seconds
• Reduce request frequency
• Contact support if limits are too restrictive for your use case

Spec Processing Errors

spec_validation_failed

{
  "error": "spec_validation_failed",
  "message": "OpenAPI spec is invalid: missing 'paths' field"
}

Cause: Uploaded OpenAPI spec doesn’t conform to the standard.

Resolution:

1. Validate your spec with an OpenAPI validator
2. Fix reported issues
3. Re-upload

unsupported_spec_version

{
  "error": "unsupported_spec_version",
  "message": "Swagger 2.0 is not supported, please convert to OpenAPI 3.x"
}

Cause: Spec version isn’t supported.

Resolution:

• Convert Swagger 2.0 to OpenAPI 3.0
• Use tools like swagger2openapi
• Supported versions: OpenAPI 3.0, 3.1

spec_too_large

{
  "error": "spec_too_large",
  "message": "Spec exceeds maximum size of 10MB"
}

Cause: The uploaded spec file is too large.

Resolution:

• Remove unnecessary examples
• Strip x-* extensions
• Split into multiple APIs if needed

Error Response Format

All Toolcog errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  // Optional additional fields:
  "details": { ... },
  "connect_url": "...",
  "retry_after": 60
}

In MCP Tool Responses

Errors from meta-tools set isError: true:

{
  "content": [{ "type": "text", "text": "Error message" }],
  "isError": true
}

HTTP Status Codes

Getting Help

If you encounter an error not listed here:

1. Check Toolcog Status for service issues
2. Search the documentation
3. Report issues at github.com/toolcog/toolcog/issues

When reporting issues, include:

• The exact error message
• Operation you were attempting
• Steps to reproduce
• Your MCP client and version