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 ...

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'],

Source: Most troubleshooting entries are derived from lessons-learned.md — check there for the latest operational insights.