Skip to main content

​
Troubleshooting

​
Quick diagnostic: rafter agent verify

Before diving into individual issues, run the built-in health check: 
rafter agent verify
This validates your config, Gitleaks binary, and all agent integrations in one pass. If something is broken, the output tells you exactly what failed and how to fix it.

​
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

​
Gitleaks not found after rafter agent init

Symptom: After initialization, rafter agent scan outputs a warning like: 
Gitleaks not found — using pattern-based scanning (21 patterns)
Cause: Gitleaks 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 Gitleaks coverage, install it separately: 
brew install gitleaks
After installing, verify with: 
rafter agent verify
# Should print: ✓ Gitleaks available on PATH
As of v0.5.2, rafter agent init prints detailed diagnostics when Gitleaks fails—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 Gitleaks), use the --skip-gitleaks flag during init, or pass --engine patterns when scanning: 
rafter agent scan . --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/skills/rafter-security.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