Troubleshooting
Fix the most common issues — connectors that won't come online, dropped channel connections, slow sandbox starts — and find where to get help.
Most issues come down to one of three things: a connector that lost contact, a channel session that dropped, or a sandbox waking from sleep. Here's how to recognize each one and get back to work fast.
Connector won't come online
A connector reports online only while it's sending heartbeats. If heartbeats stop for more than ~30 seconds, Buda marks it stale, then offline.
Confirm the connector process is running on its host machine. If the process exited or the machine slept, the heartbeat stops and the status flips to stale within ~30 seconds.
Check network egress. The connector needs outbound access to reach Buda Cloud. A firewall or proxy blocking that connection looks identical to a dead process — stale, then offline.
Restart the connector. A fresh start re-registers the device and resumes heartbeats; the status should return to online almost immediately.
Verify the API key and target Space. A connector authenticates with a key tied to a Space — a revoked or wrong key keeps it from coming online.
stale vs offline: stale means Buda hasn't heard from the connector recently but hasn't given up; offline means it's been disconnected. Both clear on the next successful heartbeat.
Channel QR / connection drops
QR-based channels (WhatsApp, Feishu, WeCom, WeChat, DingTalk) link by scanning a code, then hold a live gateway connection.
- QR expired before you scanned it. QR codes are short-lived. Reopen the channel's connect screen to generate a fresh code and scan promptly.
- Connection dropped after linking. Gateways reconnect automatically with backoff. Give it a moment before reconnecting manually — repeated manual restarts can fight the automatic retry.
- Scanned but nothing happens. Make sure you scanned with the correct account (e.g. the right WhatsApp number or Feishu workspace). Re-scan from a freshly generated QR.
- Messages not routing to an agent. Confirm the channel's default Space is the one holding the agent you expect. Channels are user-scoped and deliver tasks to their default Space.
Sandbox slow to start
Sandboxes sleep when idle to avoid running unsupervised, and wake on demand when there's new work. The first task after a sleep can feel slower because the sandbox is waking up.
- First message after a pause is slow, later ones are fast. That's the wake. Once running, the sandbox stays warm for follow-up work.
- Consistently slow on heavy tasks. CPU and memory are scoped to your Space's plan. If big jobs are bottlenecked, a higher plan provisions more resources per agent.
- Task seems stuck on start. Send a short follow-up to nudge it, or open the session detail to watch live progress across files, terminal, and browser.
Where to get help
If none of the above resolves it, reach a human:
- Email: hi@buda.im — we reply within 24 hours
- Community: Discord
- Docs: browse the FAQ for answers to common questions