Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rafter.so/llms.txt

Use this file to discover all available pages before exploring further.

​
Troubleshooting

​
Quick diagnostic: rafter agent verify

Before diving into individual issues, run the built-in health check: 
rafter agent verify
This validates your config, Betterleaks binary, and all 8 supported agent integrations in one pass. If something is broken, the output tells you exactly what failed and how to fix it. Add --probe to confirm hooks actually fire (not just that the file is on disk).

​
Python environment issues on Linux

Symptom: pip install rafter-cli fails with errors about missing ensurepip, venv, or pip. Cause: Minimal Linux installations (Ubuntu, Debian, containers) often ship with a bare Python that lacks pip and venv. Fix — install the missing system packages: 
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
Verify your Python version (must be 3.10+): 
python3 --version
pip3 --version
If you see python3: command not found after installing, check that /usr/bin/python3 exists. Some distros require python3.x (e.g., python3.12) — create a symlink or use the full path.

​
rafter --help crashes on fresh install

Symptom: Running any rafter command immediately crashes with a traceback referencing Click or Typer. Cause: Click 8.3 changed internal APIs in a way that broke Typer 0.13.x (Parameter.make_metavar() signature changed). This caused an immediate crash on any rafter invocation. Fix: Upgrade the rafter-cli package, which bundles a compatible Typer version: 
pip install --upgrade rafter-cli
If you’re pinning Typer in your own project and see this conflict: 
pip install "typer>=0.13"
Verify the fix: 
rafter --version
rafter --help

​
Betterleaks not found after rafter agent init

Symptom: After initialization, rafter secrets outputs a warning like:
Note: rafter agent scan still works but is deprecated — it will be removed in a future major version. 
Betterleaks not found — using pattern-based scanning (21 patterns)
Cause: Betterleaks (the gitleaks successor maintained by the same authors, adopted in v0.8.0) is an optional enhancement. When the binary is not on your PATH, Rafter falls back to its built-in pattern engine (21 secret patterns covering API keys, tokens, and private keys). All core functionality still works. If you want full Betterleaks coverage, the easiest path is to let Rafter manage the binary for you: 
rafter agent init --with-betterleaks
# or, for an existing install:
rafter agent update-betterleaks
That downloads the pinned, hash-verified binary to ~/.rafter/bin/betterleaks. Or install it system-wide: 
brew install betterleaks
After installing, verify with: 
rafter agent verify
# Should print: ✓ Betterleaks available on PATH (or at ~/.rafter/bin/betterleaks)
Upgrading from a pre-0.8.0 install? If you previously ran --with-gitleaks, you’ll have a leftover ~/.rafter/bin/gitleaks. rafter agent verify and rafter agent status detect this and tell you to run rafter agent update-betterleaks — they no longer error out on the legacy binary. The CLI flags --with-gitleaks, --engine gitleaks, and rafter agent update-gitleaks were removed in v0.8.0; use the -betterleaks equivalents.
rafter agent init prints detailed diagnostics when the Betterleaks binary fails to load — including binary architecture, system platform, and libc type (glibc vs musl). This helps diagnose binary incompatibilities on Linux.
If you prefer pattern-only scanning (no Betterleaks), simply omit --with-betterleaks during init, or pass --engine patterns when scanning: 
rafter secrets . --engine patterns

​
OpenClaw skill not installed after rafter agent init

Symptom: After running rafter agent init, OpenClaw does not receive the Rafter skill. The init output does not mention OpenClaw. Cause: rafter agent init detects OpenClaw by checking for the ~/.openclaw directory. If OpenClaw is installed but that directory does not exist yet (e.g., OpenClaw has never been run), detection fails silently. Fix — run OpenClaw at least once first, then re-initialize: 
# Start OpenClaw so it creates ~/.openclaw
openclaw start

# Stop it, then re-run Rafter init
openclaw stop
rafter agent init
Verify the skill was installed: 
ls ~/.openclaw/workspace/skills/rafter-security/SKILL.md
If the directory exists but skill is still missing, force reinstall: 
rafter agent init --force
Then restart OpenClaw to load the skill: 
openclaw restart
Check that the integration is enabled in config: 
rafter agent config get agent.environments.openclaw.enabled
# Should return: true
If it returns false, enable it manually: 
rafter agent config set agent.environments.openclaw.enabled true
As of v0.5.2, rafter agent init surfaces detailed error context when OpenClaw skill installation fails—including source path, destination path, and the underlying exception. Check the init output for actionable guidance.

​
Still stuck?

Get Help