> ## Documentation Index > Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```bash theme={null} # 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 ```json theme={null} { "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? ```json theme={null} // 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: ```bash theme={null} 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 ```json theme={null} // 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: ```json theme={null} { "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 ```json theme={null} { "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 ### Contact support * Email: [support@runalloy.com](mailto:support@runalloy.com) * 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 |