Troubleshooting

When something goes wrong, this guide helps you quickly identify the problem and get back on track. Start with the decision tree below, then find your specific error in the reference section.

Decision Tree: My Workflow Failed

Use this flowchart to narrow down the issue:

1. Did the workflow start at all?

   • No → Check Authentication Errors or Rate Limit Exceeded
   • Yes → Continue to step 2

2. Did it fail at a specific step?

   • The step involves an MCP tool → Check MCP Connection Failed or MCP Tool Error
   • The step is waiting for input → Check Execution Suspended
   • Yes, with a timeout → Check Step Timeout
   • Yes, with a credential error → Check Invalid or Expired Credentials

3. Did the workflow run but produce unexpected results?

   • Too many steps executed → Check Max Steps Exceeded
   • External service returned an error → Check External API Rate Limit

---

Error Reference

1. Missing Authorization Header

Symptom: API calls return {"error":"missing authorization header"} with HTTP 401.

Cause: The request did not include an Authorization header with a valid Bearer token.

Fix:

• Ensure your API client includes the header: Authorization: Bearer <your-token>
• If using the dashboard, try logging out and logging back in to refresh your session
• Check that your token has not been accidentally truncated

---

2. Invalid or Expired Token

Symptom: API calls return {"error":"token expired"} or {"error":"invalid token"} with HTTP 401.

Cause: Your authentication token has expired or is malformed.

Fix:

• Log in again to obtain a fresh token
• If using API keys, regenerate the key in Settings > API Keys
• Verify that the token is being sent as-is without modification

---

3. Execution Suspended

Symptom: The workflow status shows "suspended" and a prompt is displayed asking for your input.

Cause: A step in the workflow requires human approval or input before it can continue. This is part of Sire's Human-in-the-Loop feature.

Fix:

• Open the execution detail view in Mission Control
• Review the pending prompt and provide the requested input
• Click Resume to continue the workflow
• If the workflow was suspended in error, you can also Cancel it

---

4. Rate Limit Exceeded

Symptom: API calls return {"error":"rate limit exceeded"} with HTTP 429. A Retry-After header indicates when you can try again.

Cause: You have sent too many requests in a short period. Sire enforces per-IP rate limits to protect service availability.

Fix:

• Wait for the number of seconds indicated in the Retry-After response header
• Reduce the frequency of your API calls
• For high-volume use cases, contact support about higher rate limits on Business plans

Default limits:

---

5. MCP Server Connection Failed

Symptom: A workflow step fails with a connection error when calling an MCP tool, or the MCP Registry shows a server as "unhealthy."

Cause: The MCP server is unreachable. This could be a network issue, the server is down, or the URL is incorrect.

Fix:

1. Go to Settings > MCP Servers and check the server's health status
2. Verify the server URL is correct and accessible
3. If self-hosting an MCP server, check that it is running and the /healthz endpoint returns {"status":"ok"}
4. Check your network configuration and firewall rules
5. For Sire-hosted MCP servers (e.g., *.mcp.sire.run), contact support at support@sire.run if the issue persists

---

6. MCP Tool Returned an Error

Symptom: A workflow step completes but its output contains "isError": true with an error message.

Cause: The MCP server received the request but the underlying tool failed. Common reasons include invalid parameters, missing permissions, or the external service is down.

Fix:

• Read the error message in the step output for specific details
• Verify the tool parameters are correct (check the MCP Tool Catalog for expected parameters)
• Ensure the credentials configured for that MCP server are valid
• If the error mentions permissions, verify that the OAuth token or API key has the required scopes

---

7. Step Timeout

Symptom: A workflow step fails with a timeout error after a period of inactivity.

Cause: The step took longer to complete than the configured timeout. This can happen with slow external APIs, large data processing, or network latency.

Fix:

• Increase the step timeout in the workflow configuration
• Check whether the external service is experiencing slowness
• Break long-running operations into smaller steps
• For database queries via the SQL Connector, use the timeout parameter to set an appropriate limit

---

8. Invalid or Expired Credentials

Symptom: An MCP tool step fails with an error mentioning "credentials," "access token," "unauthorized," or "403 Forbidden."

Cause: The OAuth token or API key configured for the MCP server has expired or been revoked.

Fix:

1. Go to Settings > MCP Servers and select the affected server
2. Click Re-authorize to refresh the OAuth credentials
3. If using API keys, generate a new key from the external service's dashboard and update it in Sire
4. Verify that the token has the required permission scopes for the tools you are using

---

9. Max Steps Exceeded

Symptom: The workflow fails with an error like "execution exceeded max steps budget: executed N, max M."

Cause: The workflow ran more steps than the configured maximum. This safeguard prevents runaway workflows from consuming excessive resources.

Fix:

• Review the workflow to ensure it does not contain unintended loops
• Increase the max steps limit in the workflow settings if the workflow legitimately requires more steps
• Consider breaking the workflow into smaller, composable workflows

---

10. External API Rate Limit

Symptom: An MCP tool step fails with a message about rate limits from the external service (e.g., Twitter, Google, Microsoft).

Cause: The external API's own rate limits have been exceeded. Each service has its own quotas independent of Sire's rate limits.

Fix:

• Wait for the external service's rate limit window to reset (often indicated by a retry_after value in the error)
• Reduce the frequency of calls to that service
• Use Sire's built-in retry policy, which automatically handles transient rate limit errors with exponential backoff
• Check the external service's documentation for their specific rate limit quotas

---

Still Need Help?

If your issue is not covered above:

1. Check the execution logs: Open the failed execution in Mission Control and inspect individual step inputs, outputs, and timing
2. Search the API reference: Consult the API Reference for endpoint-specific error codes
3. Contact support: Reach out via the in-app support widget or email support@sire.run with your execution ID