Troubleshooting

Troubleshooting

Common issues and how to fix them.

Deployment issues

"Server creation timed out"

• Check your cloud provider's dashboard to see whether the server was created
• Your account may have hit a resource limit — check your provider's limits
• Try a different region

"Cloud-init took too long"

• The server is still installing its runtime
• Wait a few more minutes and check the Technical details in the progress screen
• The deployment streams logs there throughout setup

"Stack deployment failed"

• Open the Technical details log in the wizard to see which step failed
• A redeploy from a clean state is usually the fastest fix — see Full redeployment below

"OVHcloud rejected these credentials"

1. Confirm the wizard account endpoint matches the site where the API token was created
2. Use the Public Cloud API service name, not the editable project display name
3. Confirm the consumer key includes the required project and instance rules
4. Follow Deploy with OVHcloud to create a replacement restricted token

Connection issues

Private-by-default deployments do not expose internal app ports to the internet. DigitalOcean, Google Cloud, and OVHcloud deployments open public 443 only when a selected channel requires inbound webhook delivery. Telegram stays private and uses outbound polling. Other providers need a separate HTTPS entrypoint.

"Can't access the dashboard"

1. Make sure Tailscale is running on your device
2. Check that both your device and the server are on the same Tailscale network
3. Try the Tailscale IP directly: http://100.x.x.x:3000

"Telegram bot not responding"

1. Open the management dashboard first (http://<tailscale-ip>:3000) and go to Connect AI & Messengers
2. Use the Agent selector to choose the right agent
3. Confirm Telegram shows as configured there
4. If the bot is already replying in chat, ask it to connect the missing provider there instead of pasting secrets
5. Verify the bot token works: visit https://api.telegram.org/botYOUR_TOKEN/getMe

"Pairing required" in the agent UI

1. Return to the management dashboard (:3000) and run setup from Connect AI & Messengers
2. Use the Agent selector to choose the affected agent
3. If shown, click Fix Pairing Automatically in the setup checklist
4. If pairing still fails, restart the agent from the Agents page

"WhatsApp webhook verification failed"

1. Double-check the callback URL in Meta's developer console
2. Verify the verify token matches the value shown in Dashboard → Connect AI & Messengers → WhatsApp
3. Make sure your HTTPS entrypoint forwards to /webhook/whatsapp/YOUR_DEPLOY_ID

AI provider issues

"OAuth token expired"

• Your agent automatically refreshes OAuth tokens
• If refresh fails, reconnect from chat by asking the bot to connect ChatGPT or Claude again, or use Connect AI & Messengers in the dashboard

"API key invalid"

• Verify the key at the provider's dashboard
• Check whether the key was revoked or expired
• Update the key from chat (if the bot is live) or in your agent's dashboard settings

"Model not available"

• Your subscription plan may not include the default model
• The agent automatically falls back to the next best model
• You can manually select a different model in dashboard settings

Performance issues

"Agent responding slowly"

• Consider upgrading to a larger server size
• Reduce the number of agents if you're running several
• Check your AI provider's status page for outages

"Database running out of space"

• Enable conversation pruning in Dashboard → Settings
• Run a manual cleanup with Settings → Clean up now
• Resize the server's disk via your cloud provider

Recovering from errors

Restart a single agent

From the master dashboard, find the agent card and click Restart.

Full redeployment

If things are severely broken, tear down and redeploy:

1. Go to the wizard
2. Click Destroy on your existing deployment
3. Re-run the wizard