Troubleshooting

Common issues

Authentication failures

• Confirm the user is signed into the app.
• Confirm the request is hitting the correct environment.
• Check whether the route expects a company or workspace id.

Stripe events not updating the app

• Verify the provider keys are saved with the expected test/live prefix.
• Confirm the webhook or checkout route is being hit from the right environment.
• Check that the billing flow waits for the event or payment confirmation before updating UI state.

MCP tool calls missing data

• Confirm the MCP server has the right API keys and OAuth client records.
• Check the remote server URL generated by /api/mcp/server.
• Log the exact tool input and the upstream response.

Custom domain not loading

• Recheck DNS propagation.
• Verify the domain record was verified in the app.
• Confirm the portal host matches the configured canonical domain.

Ask AI reports no endpoints

• Confirm OPENROUTER_API_KEY is present in the docs-site environment.
• Set OPENROUTER_MODEL=openrouter/auto if you want OpenRouter to route to an available model automatically.
• Restart the dev server after changing the AI env vars.

What support needs

When a problem is reported, capture:

• the user or workspace id,
• the environment,
• the request id,
• the timestamp,
• and the exact visible error.

That is enough to trace most issues without reproducing them from scratch.