Troubleshooting

Common Issues & Solutions

Authentication Errors

”Invalid or missing authentication” (401)

Problem: Your API key or JWT token is invalid or missing.

Solutions:

• Verify your API key is correct and hasn’t been regenerated
• Check that you’re including the Authorization: Bearer header
• For JWT tokens, ensure they haven’t expired
• Make sure you’re using the correct header format

# Correct format
Authorization: Bearer your_api_key_here
x-alloy-userid: your_user_id_here

# Common mistakes
Authorization: your_api_key_here  # Missing "Bearer" prefix
x-user-id: ...  # Wrong header name (should be x-alloy-userid)

”Rate limit exceeded” (429)

Problem: You’ve exceeded 100 requests per minute.

Solutions:

• Implement exponential backoff in your retry logic
• Batch operations where possible
• Consider caching frequently accessed data
• For high-volume use cases, contact support for rate limit increases

MCP Protocol Issues

”Credential not found” error

Problem: The connector requires authentication but no credential exists.

Solutions:

1. First create a credential using the create_credential_alloy tool
2. List existing credentials with get_credentials_alloy
3. Pass the credential ID in your action execution

{
  "name": "execute_action_alloy",
  "arguments": {
    "connectorId": "slack",
    "actionId": "chat_postMessage",
    "credentialId": "cred_abc123",  // Include credential ID
    "parameters": { ... }
  }
}

”Action not found” error

Problem: The action ID doesn’t exist for this connector.

Solutions:

• Use get_connector_resources_alloy to list available actions
• Check for typos in the action ID (case-sensitive)
• Verify the connector supports the action you’re trying to use

Server Configuration Issues

Server not accepting requests

Problem: Getting 403 Forbidden errors.

Check these restrictions:

1. User restrictions: Is your user ID allowed?
2. Connector restrictions: Is the connector in your allowlist?
3. Action restrictions: Is the specific action blocked?
4. Public/Private mode: Are you using the correct authentication?

// Example: Check your server's restrictions
GET /api/servers/{serverId}

// Response will show active restrictions
{
  "restrictions": {
    "connectors": {
      "mode": "allowlist",
      "allowedIds": ["slack", "notion"]  // Only these are allowed
    }
  }
}

Token URL not working

Problem: Self-sufficient token URL returns 401.

Possible causes:

• Token has expired (check tokenExpiresInDays setting)
• Server was deleted
• Token was regenerated

Solution: Get a fresh token URL by fetching server details again.

OAuth & Credential Issues

OAuth redirect not working

Problem: OAuth flow fails or redirects to wrong URL.

Solution: Include the x-redirect-uri header:

POST /mcp/{serverId}/{token}
x-redirect-uri: https://your-app.com/oauth/callback
Content-Type: application/json

API Key credentials not working

Problem: Non-OAuth credentials fail to authenticate.

Common issues:

1. Wrong field names: Each connector expects specific field names
2. Missing required fields: Some connectors need multiple fields

// Example: Creating ShipStation credentials
{
  "name": "create_credential_alloy",
  "arguments": {
    "connectorId": "shipStation-oas",
    "authenticationType": "apiKey",
    "fields": {
      "api-key": "your_key",     // Exact field name required
      "api-secret": "your_secret" // Both fields needed
    }
  }
}

Use get_credential_metadata_alloy to see exact requirements.

Data & Response Issues

”needsRefinement” response

Problem: Getting guidance instead of data.

This happens when:

• Result set is too large (>50 items)
• Platform API would be overwhelmed
• More specific parameters are needed

Solution: Add filtering parameters:

{
  "parameters": {
    "limit": 10,        // Limit results
    "query": "search",  // Add search terms
    "status": "active"  // Filter by status
  }
}

Truncated responses

Problem: Response data is cut off.

By design: Responses are limited to prevent overwhelming the AI.

• Arrays: Maximum 25 items shown
• Strings: Maximum 5KB per field
• Use pagination for more data

Debugging Tips

1. Enable verbose logging

Check response headers and error details for more context.

2. Test incrementally

1. First test authentication with a simple tools/list call
2. Then try listing connectors
3. Finally attempt your actual operation

3. Validate your request format

{
  "jsonrpc": "2.0",          // Required
  "method": "tools/call",     // Exact method name
  "params": {                 // Parameters object
    "name": "tool_name",
    "arguments": { ... }
  },
  "id": "unique_id"          // Request ID
}

Getting Help

Check the documentation

Authentication Guide

API Reference

Available Tools

Contact support

• Email: [e-mail]
• Include: Request ID, error messages, and code samples

Common error codes reference

Code	Meaning	Action Required
INVALID_REQUEST	Malformed request	Check JSON syntax
UNAUTHORIZED	Auth failed	Verify credentials
FORBIDDEN	Access denied	Check restrictions
NOT_FOUND	Resource missing	Verify IDs exist
RATE_LIMITED	Too many requests	Implement backoff
CREDENTIAL_NOT_FOUND	No auth for connector	Create credential
CONNECTOR_NOT_FOUND	Invalid connector	Check connector ID
ACTION_NOT_FOUND	Invalid action	Verify action exists