Troubleshooting

v1 status: seeded with the most common failures from rantaiclaw doctor and the codebase’s known sharp edges. The canonical reference in the upstream repo is docs/troubleshooting.md.

Install / first run

rantaiclaw: command not found The installer placed the binary in ~/.cargo/bin or ~/.local/bin, neither of which is on your PATH. Re-run the bootstrap and copy the export PATH=... line it prints into your shell rc.

failed to verify checksum The download was corrupted or tampered with mid-flight. Re-run the bootstrap; if it persists, file an issue with your platform info.

Provider

provider api_key invalid Your credential was revoked or never set. Run rantaiclaw setup, pick the same provider, the wizard overwrites the secret in the encrypted inline enc2:<hex> value.

provider rate_limited / 429 Transient. The ReliableProvider wrapper retries with exponential backoff (capped at 10s) and rotates through [reliability].api_keys if you’ve supplied multiple. If it persists, switch to a higher-tier API key, configure a fallback provider, or add per-model fallback chains.

context window exceeded The retry wrapper recognizes this as non-retryable and surfaces it. Trim the context (shorter system prompt, smaller K for memory recall) or move to a model with a larger context window.

Channels

channel <name> offline / not responding Most likely the bot token is wrong, the bot was kicked from its allowlisted chat, or the network is unreachable. Verify the bot in the platform’s UI, then re-run rantaiclaw doctor.

channel <name> empty allowlist You enabled the channel but did not add anyone to its allowlist. Most channels treat empty allowlist as offline (deny-by-default). Check the right config key — see Reference → Channels for the per-channel allowlist key names (allowed_users / allowed_contacts / allowed_from / allowed_numbers / allowed_senders).

Email replies to everyone, not just my allowlist Email is the one channel that allows-all on empty allowed_senders. Set explicit allowed senders or domain prefixes (@example.com) to restrict it.

WhatsApp bot “types but never replies”, or your owner commands are ignored WhatsApp delivers many direct chats through a privacy LID (<id>@lid) rather than your phone number. On older builds the reply landed in a hidden LID thread you never see (so the bot appeared to “type but never reply” — fixed in v0.6.91), and the inbound sender was the opaque LID, so it never matched approval_owners and you were silently treated as a guest — owner-only features (cron, permissions, owner commands) went dark and surfaced as empty / “no final answer” replies (fixed in v0.6.93). Upgrade to >= 0.6.93, then set your real phone number in [channels_config.whatsapp].allowed_numbers (instead of *) and in [channels_config].approval_owners.

Duplicate or contradictory replies, Telegram getUpdates 409 Conflict, or gateway :3000 address already in use Two processes are running the same channel — most often a background daemon and an interactive TUI both polling one bot token, or two daemons. Run exactly one runner per token. Since v0.6.92 (single-runner) a TUI defers channel startup to a live daemon via the .daemon_active sentinel and every listener holds an advisory per-channel lock, so upgrade to >= 0.6.92 and let the daemon own the channel while the TUI defers.

Gateway

Refusing to bind to 0.0.0.0 — set [gateway].allow_public_bind = true Exactly what it says. Add allow_public_bind = true to [gateway], or change host back to 127.0.0.1. Alternative: set RANTAICLAW_ALLOW_PUBLIC_BIND=1 in env.

webhook signature mismatch Either the HMAC secret is wrong, or the request was tampered with mid-flight. Verify the secret matches the upstream service’s webhook configuration. Note: only the channel-specific endpoints (/whatsapp, /linq, /nextcloud-talk) verify HMAC over the body. The generic /webhook endpoint uses an X-Webhook-Secret shared secret check, not body HMAC.

Pairing token rejected Tokens are stored as SHA-256 hashes — you cannot recover them from [gateway].paired_tokens. Pair again via POST /pair with X-Pairing-Code to issue a fresh token.

Approval / Autonomy

Tool calls from Discord/Slack are silently denied Channels have an in-chat approval relay (since v0.6.84, src/channels/approval_relay.rs): when the agent needs approval, the bot posts a prompt to the chat and an authorized owner approves it inline. Reply /approve — or a bare approve, yes, y, ok — to allow the single pending request; /deny or no rejects it and is honored from anyone (stopping an action is always safe). With multiple requests pending, the bot lists them and asks you to pick one by name. Only senders in [channels_config].approval_owners may approve — being able to chat with the bot does not grant approval authority. For unattended setups where no one is watching the chat, add the tool to [autonomy].auto_approve instead, or for shell commands add a pattern to <profile>/policy/command_allowlist.toml.

rantaiclaw chat hangs after a tool call The CLI approval prompt blocks on stdin.read_line with no timeout — timeout_secs is written to the policy file but no consumer reads it yet. Type y or n. If you’ve launched the agent in a non-interactive context where stdin isn’t connected, add the tool to auto_approve instead.

MCP

mcp server <name> launcher not on PATH rantaiclaw doctor’s MCP check only verifies the launcher binary (npx, node, etc.) is on PATH. Install it, then re-run doctor.

mcp server <name> initialize failed (during setup) The initialize handshake only runs during interactive rantaiclaw setup mcp (5s timeout). If it fails: run the configured command args manually outside RantAIClaw to see the error. Common cause: missing env vars or wrong args.

Why isn’t the LLM calling my MCP tools? Today the MCP supervisor only manages processes — it does not yet register MCP-server tools with the agent loop. This is documented work-in-progress; see MCP Servers.

Sandbox

landlock unsupported on this kernel Landlock requires Linux ≥ 5.13. Either upgrade the kernel or accept the warning — RantAIClaw’s sandbox auto-detection falls through to the next available backend (Firejail → Bubblewrap → Docker → Noop).

sandbox-bubblewrap requires --features sandbox-bubblewrap Bubblewrap is feature-gated at build time. Rebuild with cargo build --release --features sandbox-bubblewrap, or pick a different backend in [security.sandbox].

Memory

memory backend postgres requires --features memory-postgres You configured [memory] backend = "postgres" with a binary built without the feature. Rebuild with cargo build --release --features memory-postgres, or use the sqlite / lucid backend instead.

Recall returns nothing useful The default embedding provider is none — recall is purely lexical (BM25) until you configure a real embedding provider:

[memory.embedding]
provider = "openai"
model = "text-embedding-3-small"

Plus an API key in env or in the appropriate provider block.

brain.db missing after a redeploy If you enabled [memory] snapshot_enabled = true, Core memories are auto-hydrated from MEMORY_SNAPSHOT.md on cold boot. Otherwise the agent starts fresh. Mount the workspace volume between deploys to preserve memory.

Knowledge Base

kb_not_configured The Knowledge Base has no embedding API key resolved, so it cannot embed or search — this message is raised in src/kb/axi/api.rs. Fix it by running rantaiclaw setup knowledge (which stores the key encrypted in the [knowledge] config block) or by exporting KB_EMBEDDING_API_KEY. The optional OCR/vision key KB_EXTRACT_VISION_API_KEY falls back to the embedding key when unset, and OPENROUTER_API_KEY is the final fallback. Added in v0.7.0. See the Knowledge Base recipe and Knowledge Base → Configuration.

Profile / paths

Where is my config? Default: ~/.rantaiclaw/profiles/default/config.toml. Override with --profile <name>, RANTAICLAW_PROFILE=<name>, or RANTAICLAW_CONFIG_DIR=<path>. Same path shape on Linux, macOS, and Windows.

active_profile says one thing but --profile flag overrides it — which wins? The --profile flag wins. Resolution order: --profile → RANTAICLAW_PROFILE → ~/.rantaiclaw/active_profile → default.

config.runtime.toml doesn’t seem to take effect Correct — the loader exists in src/config/runtime.rs but is not currently called from Config::load_or_init. Live overrides via that file are planned but not yet wired. Edit config.toml directly.