Skip to content
BrainRoad BrainRoad
Documentation Menu

Common Issues

Quick fixes for the most frequently encountered problems.

On this page

Agent Will Not Start

If your agent fails to start or gets stuck on a boot screen, check these in order:

1. Verify you have at least one valid API key

Your agent needs at least one working API key to start. It cannot boot without one.

  • Go to Settings in the sidebar
  • Confirm you have at least one key listed

If you see no keys:

  • Click Add Key
  • Either activate your trial (if available) or add your own provider key

If the key is marked as invalid or rotated, update it:

  • Go to your provider’s dashboard (Anthropic, OpenAI, etc.)
  • Generate a new key or verify the old one still works
  • Update the key in the Keys section

2. If you recently rotated your API key, reload it

If you changed your key at the provider’s dashboard but your agent still will not start:

  1. Go to Settings in the sidebar
  2. Delete the old key (click the trash icon)
  3. Add the new key from your provider
  4. Try starting your agent again

3. Check for connectivity issues

If your gateway is stopped or unable to reach your provider:

  1. Go to your agent’s detail page
  2. Click Stop in the top-right corner
  3. Wait 5 seconds for a full shutdown
  4. Click Start

This reinitializes the connection to your API provider. Wait 15-30 seconds for the agent to boot fully.

4. Still not starting?

If your agent is still stuck after trying the above:

  1. Go to Activity tab and scroll to the bottom to see the latest log entries — look for error messages
  2. Try stopping and restarting once more
  3. If the error mentions a specific provider (e.g., “Anthropic API error”), verify your API key is correct in their dashboard
  4. Contact support with a screenshot of the error and your provider name

Setup Wizard Is Stuck or Shows “Wizard Already Running”

This happens when a previous wizard session did not close cleanly. It can occur if:

  • You closed the browser tab while the wizard was running
  • Your internet connection dropped during setup
  • Your browser or the agent container crashed

How to fix: Click Restart Agent on the wizard page. Wait for the agent to restart (about 30 seconds), then the wizard will automatically retry. Your existing agent configuration is preserved — the wizard will layer new settings on top of what you already configured.

If you still see the same error after restarting, try these additional steps:

  1. Close the wizard tab completely
  2. Go back to your agent detail page in the dashboard
  3. Stop the agent (click the Stop button in the top-right corner)
  4. Wait 10 seconds for it to stop completely
  5. Start the agent again
  6. Try running the setup wizard again

Slow Responses

Your agent’s response speed depends on the AI provider. If responses are slow, check your API key’s rate limits and quota at the provider’s dashboard. Free-tier API keys often have strict rate limits that throttle response times. Upgrading your API plan at the provider usually resolves this.

Dashboard Not Loading

Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R). If the page still does not load, clear your browser cache and try again. If you are on a corporate network, check that WebSocket connections to app.brainroad.com are not blocked by a firewall or proxy.