.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
There's a Reddit thread titled "A cautionary tale about ZeroClaw: Great concept, but an absolute nightmare to set up." It has dozens of comments from people who ran into the same handful of issues and got stuck. The frustrating part is that most of these problems have straightforward fixes once you know where to look. This guide compiles the errors people actually hit, with the actual solutions that work.
Start with zeroclaw doctor
Before diving into specific errors, run the built-in diagnostics:
zeroclaw doctorThis command checks your configuration file, provider connectivity, channel health and system resources. It reports problems in plain language with suggestions for fixing them. About half the time, running zeroclaw doctor tells you exactly what's wrong and you don't need to read any further. The other half is what this article covers.
zeroclaw: command not found
This is the single most common issue people report after installation. It means the ZeroClaw binary isn't in your shell's PATH. The fix:
export PATH="/root/.cargo/bin:$PATH"To make this permanent so it survives reboots and new SSH sessions, add it to your shell profile:
echo 'export PATH="/root/.cargo/bin:$PATH"' >> /root/.bashrc
source /root/.bashrcIf you installed ZeroClaw from a pre-built binary or a 1-click VPS template, the PATH should already be configured. If it isn't, something went wrong during provisioning. The export command above fixes it regardless of how ZeroClaw was installed.
Setup complete but bot doesn't respond
This is the "dead chatbot" problem that comes up on Reddit constantly. You finish the setup wizard, everything looks correct, you message your Telegram bot and... nothing. No response, no error, just silence.
Work through these checks in order:
1. Is ZeroClaw actually running?
zeroclaw service statusIf the service isn't active, start it. If you haven't installed the service yet, the bot only works while you have an active SSH session with zeroclaw daemon running in the foreground.
2. Is the provider reachable?
zeroclaw agent -m "Hello"If this returns an error, the problem is between ZeroClaw and your AI provider. Check that your API key is correct and that you have credits on your account. Run zeroclaw doctor for a more detailed provider connectivity report.
3. Is the channel connected?
zeroclaw channel list
zeroclaw channel doctorThe channel list should show your Telegram bot (or whichever channel you're using) as active. If it shows disconnected or missing, rebind the channel with your bot token. For Telegram specifically, make sure you've sent /start to your bot in the Telegram app. Without that initial interaction, the bot can't send you messages.
4. Is the gateway running?
If you're running ZeroClaw through the daemon or gateway command instead of the systemd service, the gateway needs to be active for channels to receive webhooks. Check with zeroclaw status and look for the gateway line.
Provider API errors
These usually show up as error messages mentioning authentication, rate limits or model not found.
Authentication failed or invalid API key — Open ~/.zeroclaw/config.toml and double-check the api_key value. Common mistakes include extra whitespace around the key, copying the key with quotes that don't belong, or using a key from the wrong provider. Run zeroclaw auth status to see which provider credentials ZeroClaw recognizes.
Model not found — The model name in your config must exactly match what the provider expects. For Ollama, run ollama list and use the exact tag including the version suffix (like llama3.1:8b, not just llama3.1). For cloud providers, check the provider's documentation for current model names since they change occasionally.
Rate limit exceeded — Cloud providers enforce rate limits, especially on free tiers. If you're hitting limits, either upgrade your API plan, add a delay between requests in your cron jobs, or switch to a local model with Ollama for high-volume tasks.
Channel-specific issues
Telegram: bot connects and immediately disconnects — This almost always means the Message Content Intent isn't enabled. For Discord this is a required step in the developer portal. For Telegram, the issue is usually an invalid or revoked bot token. Regenerate the token in BotFather with /revoke followed by /newbot or /token, then rebind it in ZeroClaw.
Discord: "Invalid Session" errors in a loop — If you're using the Discord channel, you need to enable the Message Content Intent in the Discord Developer Portal under your application's Bot settings. Without it, ZeroClaw's Discord channel connects, fails to read messages, disconnects, reconnects and repeats forever. This is the most common Discord setup issue and it's easy to miss.
WhatsApp: QR code scan doesn't connect — The WhatsApp Web channel requires an active phone session. If your phone disconnects from the internet or WhatsApp logs out the web session, ZeroClaw loses the connection. The WhatsApp Business Cloud API channel is more reliable for always-on setups but requires a Meta Business account. Check the channels reference for the differences between the two WhatsApp modes.
Build failures (self-installers only)
If you're compiling ZeroClaw from source rather than using a pre-installed template, build failures on low-resource VPS plans are common. The Rust compiler is memory-hungry during compilation.
Signal 9 / OOM killer / "cannot allocate memory" — Your VPS doesn't have enough RAM to compile. The ZeroClaw project recommends at least 2 GB of RAM plus swap for compilation, with 4 GB+ being comfortable. If you're on a 1-2 GB plan, use prebuilt binaries instead:
./bootstrap.sh --prefer-prebuiltBuild stuck or extremely slow — Rust compilation is single-threaded for some crates. On a 1 vCPU plan, a full build can take 15-30 minutes. If it seems stuck, give it time. If it's been over an hour, check disk space with df -h because the build directory needs several GB of free space.
After an update, nothing works
First thing after any ZeroClaw update:
zeroclaw doctorThe doctor command checks for configuration format changes, deprecated options and compatibility issues introduced by the update. If the update changed config file syntax (which happens occasionally between minor versions), zeroclaw doctor usually tells you exactly what needs to change.
If the service fails to start after an update, check the logs. On systems using the systemd service:
journalctl -u zeroclaw --since "10 minutes ago"This shows recent log entries from the ZeroClaw service, which often contain the specific error that's preventing startup. The production hardening guide covers how to set up proper log collection for ongoing monitoring.
