Skip to main content

Troubleshooting

Common problems and their solutions, collected from operational experience.

Beads CLI Issues​

bd ready returns nothing but work exists​

Symptom: bd list --status=open shows beads, but bd ready is empty.

Cause: All open beads have unresolved blockers.

Fix:

bd blocked                    # See what's blocking what
bd dep tree <id>              # Inspect dependency chain
bd close <blocker-id>         # Close completed blockers

Staleness errors after git pull​

Symptom: bd reports stale data after pulling changes.

Fix:

bd import --force -i .beads/issues.jsonl

Dolt database corruption​

Symptom: bd commands fail with database errors.

Cause: Usually concurrent access (Dolt is not concurrent-safe).

Fix:

# If JSONL is the source of truth, wipe and reimport
rm -rf .beads/dolt
bd import -i .beads/issues.jsonl
caution

bd import does INSERT, not UPSERT. Always wipe the Dolt directory before reimporting to avoid duplicate key errors.

bd show --json returns an array​

This is expected behavior — bd show --json always returns an array, even for a single ID. Parse accordingly:

bd show <id> --json | jq '.[0]'

Labels missing from bd ready --json output​

Known behavior: bd ready --json does not include the labels field. Use bd show <id> --json or bd list --json to get labels.

Also note: beads without labels omit the labels key entirely — check for a missing key, not an empty array.

Agent & Container Issues​

OpenClaw gateway dies after agent deletion​

Symptom: Gateway stops but systemd doesn't restart it.

Cause: openclaw agents delete triggers a config reload. Gateway exits cleanly (code 0), but Restart=on-failure only triggers on non-zero exits.

Fix:

ssh mimas sudo systemctl start openclaw-gateway

Prevention: Always check gateway status after deleting agents.

Container permission denied (SELinux)​

Symptom: Rootless Podman containers get permission denied on bind-mounted directories despite correct Unix permissions.

Cause: SELinux on Fedora requires container file context labels.

Fix:

chcon -Rt container_file_t /path/to/workspace

Agent can't push to GitHub​

Symptom: git push fails inside agent container.

Cause: Git auth relies on a bind-mounted env file at /etc/openclaw/env. If mounted at the wrong path, gh-wrapper.sh can't find credentials.

Fix: Verify the bind mount destination matches /etc/openclaw/env (not /home/openclaw/.openclaw/env).

Rootless Podman containers invisible to other users​

Symptom: podman ps shows no containers, but agents are running.

Cause: Rootless Podman containers are user-scoped. User A cannot see User B's containers.

Fix: Run podman ps as the user who owns the containers (typically openclaw):

sudo -u openclaw podman ps

Infrastructure Issues​

ICU library mismatch breaks bd​

Symptom: bd crashes with ICU-related errors after an OS upgrade.

Cause: dnf upgrade on Fedora may update ICU libraries that bd was linked against.

Fix: Reinstall the bd binary from the latest release.

SSH subprocess hangs in Ludus CLI​

Symptom: Ludus CLI commands that use SSH hang indefinitely.

Cause: subprocess.run without stdin=subprocess.DEVNULL inherits stdin. Rich (used by Typer) sets stdin to non-blocking, causing SSH to wait.

Fix: This is fixed in the Ludus CLI. If you encounter it in custom scripts, always pass stdin=subprocess.DEVNULL for non-interactive SSH calls.

run_as_openclaw doesn't source environment​

Symptom: Commands run via run_as_openclaw can't access GH_TOKEN and similar env vars.

Cause: run_as_openclaw does not source /etc/openclaw/env.

Fix: Pass env vars explicitly or source the env file in the command:

source /etc/openclaw/env && gh repo clone ...

bd import doesn't preserve labels​

Symptom: Labels are missing after importing from JSONL.

Cause: Known bug in bd v0.55.4 — bd import does not restore labels from JSONL.

Fix: Apply labels manually after import. The intercom-init.sh script has a post-import bd label add workaround. See PR #1966 for the upstream fix.

bd sync deprecated​

Symptom: bd sync command fails or behaves unexpectedly.

Cause: Deprecated since bd v0.55+.

Fix: Use bd export + git push (JSONL) or bd dolt push/pull (Dolt-native) instead.

bd export writes nothing in sandbox mode​

Symptom: bd export completes successfully but produces an empty file.

Cause: Sandbox auto-detection (--no-auto-flush) causes export to write nothing without an explicit output path.

Fix:

bd export -o .beads/issues.jsonl

Shell Scripting Pitfalls​

set -e aborts on list processing​

Problem: With set -e, one bad bead ID in a loop aborts all processing.

Fix: Use || warn per-item instead of relying on set -e:

for id in $ids; do
    bd show "$id" --json || echo "WARN: failed to show $id"
done

((i++)) fails with set -e​

Problem: When i=0, the old value (0 = falsy) returns exit code 1, triggering set -e.

Fix: Use i=$((i + 1)) instead.

BEADS_DIR not available in piped commands​

Problem: BEADS_DIR=x cmd1 | cmd2 only sets the variable for cmd1, not cmd2.

Fix: Export the variable first:

export BEADS_DIR=/path/to/.beads
cmd1 | cmd2

Tabula Issues​

Symptom: npm run build fails with a broken links error.

Cause: Tabula uses onBrokenLinks: 'throw' — any internal or external link that doesn't resolve fails the build.

Fix: Check the error message for the specific broken link. Fix the path or URL.

Mermaid diagrams don't render​

Symptom: Mermaid code blocks show as raw text.

Cause: Missing @docusaurus/theme-mermaid package or markdown.mermaid: true not set in config.

Fix:

npm install @docusaurus/theme-mermaid

Then verify docusaurus.config.ts has:

markdown: { mermaid: true },
themes: ['@docusaurus/theme-mermaid'],

OpenClaw Gateway & Queue​

Agent dispatch blocks cron jobs​

Symptom: Cron jobs that dispatch messages to agents take minutes to complete instead of seconds.

Cause: openclaw agent CLI is blocking — it waits for the agent run to finish before returning.

Fix: Use gateway call chat.send instead — it's non-blocking (~4s), returns immediately with {"runId": "...", "status": "started"}:

openclaw gateway call chat.send --params '{
  "sessionKey": "agent:<name>:main",
  "message": "...",
  "idempotencyKey": "<unique>"
}'

Messages don't reach the agent​

Symptom: chat.send succeeds but the agent never processes the message.

Cause: Session key mismatch. --agent <id> targets agent:<id>:main, but --session-id <custom> maps to a different internal key.

Fix: Always use the canonical session key format: agent:<name>:main.

Queued messages lost between CLI and API​

Symptom: Messages queued via chat.send while openclaw agent CLI holds a session don't get processed.

Cause: Known issue on v2026.3.24 — CLI→API queue interaction is broken. Followup messages don't auto-drain after a CLI run ends.

Fix: Use chat.send (API) for all fire-and-forget dispatches. Reserve openclaw agent CLI only for interactive use where you need the response synchronously.

caution

Don't run openclaw agent --local and gateway call chat.send targeting the same session in parallel — file-lock timeout (10s) can lose messages. Both callers must go through the same gateway process.

Test VM Issues​

E2E tests interfere with production cron​

Symptom: E2E test results are inconsistent or have extra beads.

Cause: Running E2E tests on production (mimas) — the bridge cron creates beads in parallel with test bridge runs.

Fix: Always use the isolated test VM:

LUDUS_HOST=mimas-test uv run pytest tests/e2e/ -v

GitHub API propagation delay​

Symptom: Bridge sees empty issues list immediately after creating an issue.

Cause: GitHub API needs ~3s propagation after issue/PR creation.

Fix: Add time.sleep(3) between creation and bridge run in E2E tests.

GitHub App bots can't post REQUEST_CHANGES reviews​

Symptom: Review creation fails when using REQUEST_CHANGES event type.

Cause: GitHub App bots are restricted to COMMENT and APPROVE review types.

Fix: Use COMMENT event type for review feedback in E2E tests and bot workflows.