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

> Common installation and runtime issues with Rafter local security

# Troubleshooting

## Quick diagnostic: `rafter agent verify`

Before diving into individual issues, run the built-in health check:

```bash theme={null}
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:**

<CodeGroup>
  ```bash Ubuntu / Debian theme={null}
  sudo apt update && sudo apt install -y python3 python3-pip python3-venv
  ```

  ```bash Fedora / RHEL theme={null}
  sudo dnf install python3 python3-pip
  ```

  ```bash Alpine (containers) theme={null}
  apk add python3 py3-pip
  ```
</CodeGroup>

**Verify your Python version** (must be 3.10+):

```bash theme={null}
python3 --version
pip3 --version
```

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

***

## `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:

```bash theme={null}
pip install --upgrade rafter-cli
```

If you're pinning Typer in your own project and see this conflict:

```bash theme={null}
pip install "typer>=0.13"
```

**Verify the fix:**

```bash theme={null}
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:

```bash theme={null}
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:

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install betterleaks
  ```

  ```bash Linux (binary) theme={null}
  # Download the latest release from https://github.com/betterleaks/betterleaks/releases
  # Example for Linux amd64:
  curl -sSL https://github.com/betterleaks/betterleaks/releases/latest/download/betterleaks_linux_amd64.tar.gz \
    | tar -xz -C /usr/local/bin betterleaks
  ```

  ```bash Go install theme={null}
  go install github.com/betterleaks/betterleaks/v1@latest
  ```
</CodeGroup>

After installing, verify with:

```bash theme={null}
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.

<Tip>`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.</Tip>

**If you prefer pattern-only scanning** (no Betterleaks), simply omit `--with-betterleaks` during init, or pass `--engine patterns` when scanning:

```bash theme={null}
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:

```bash theme={null}
# 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:**

```bash theme={null}
ls ~/.openclaw/workspace/skills/rafter-security/SKILL.md
```

**If the directory exists but skill is still missing**, force reinstall:

```bash theme={null}
rafter agent init --force
```

Then restart OpenClaw to load the skill:

```bash theme={null}
openclaw restart
```

**Check that the integration is enabled in config:**

```bash theme={null}
rafter agent config get agent.environments.openclaw.enabled
# Should return: true
```

If it returns `false`, enable it manually:

```bash theme={null}
rafter agent config set agent.environments.openclaw.enabled true
```

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

***

## Still stuck?

<Card title="Get Help" icon="question">
  * Documentation: [docs.rafter.so](https://docs.rafter.so)
  * GitHub Issues: [rafter-cli/issues](https://github.com/raftersecurity/rafter-cli/issues)
  * Support: [rafter.so/help](https://rafter.so/help)
</Card>