# Troubleshooting Start with `cireilclaw dry-run` to distinguish configuration failures from runtime or provider failures. Runtime logs are written as JSON events under `/logs/`. Increase terminal detail with `run --level debug` or `run --level trace` while reproducing a problem. Do not include tokens, OAuth credentials, or private message content when sharing diagnostics. ## Common failures ### Configuration errors A missing required file, invalid TOML, or an unknown key fails loudly at startup or in `dry-run`. Fix the reported file and re-run `dry-run`. ### Access denied for a path If a conditional path is not accessible in the current context, check the rules in `conditions.toml`, whether the current session context matches the `when` conditions, and whether a `deny` rule takes precedence. ### Conditional blocks not loading Verify the block file exists at `blocks/conditional/.md` with valid TOML frontmatter and a `description`, and that the rule key matches the file name. ### Plugin failures A plugin that fails to load prevents the runtime from starting. Confirm the entry is listed in `plugins.toml`, the package or directory resolves, the entry module exports a `default` factory, and the plugin's tools are enabled in the agent's `tools.toml`. ### Missing bwrap The `exec` tool requires a working `bwrap` binary on the host for the default sandbox backend. Install Bubblewrap or enable a different backend. ### Migrations If a migration fails, check the logs, restore the runtime from a backup, and re-run `cireilclaw migrate` after fixing the cause. ### Bot appears offline while the runtime is healthy A half-open gateway connection leaves sessions, heartbeats, and REST sends working while the bot answers nothing in Discord. The runtime detects this itself: it tracks gateway traffic, including the heartbeat acknowledgements that a healthy connection always exchanges, and reconnects after `gatewaySilenceTimeout` seconds without any. Search the logs for `Discord gateway` entries to see the detection and each recovery step. If the bot still looks offline after those entries, verify the bot token and that the required gateway intents are enabled in the Discord Developer Portal.