Operations

Troubleshooting

Last updated: 2026-04-30

Common failure modes and the one-line fixes. If your issue isn't here, re-run with FASTPACE_DEBUG=1 to print the full stack trace and email it to security@fastpace.net.

fastpace: command not found

The CLI installed but isn't on your PATH. Find your npm global bin directory and add it: 

npm config get prefix
# returns e.g. /Users/you/.npm-global

# Add the bin/ to PATH:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
which fastpace      # should now resolve

fastpace ui exits silently or with no output

Pre-0.22.0 versions exited 0 on startup errors with no message. Upgrade and re-run; you'll see actionable hints (port in use, permission denied, etc.). Or force the diagnostic: 

FASTPACE_DEBUG=1 fastpace ui

Port already in use

fastpace ui --port 7778
# or
FASTPACE_PORT=7778 fastpace ui

# find what's holding 7777:
lsof -i :7777

npm ERR! code ENOWORKSPACES

npm refuses commands inside a workspace root. Two clean ways to install from a checkout: 

# Option A — bypass workspaces:
cd packages/fp && npm link --no-workspaces

# Option B — install from absolute path (run from outside the monorepo):
npm install -g /path/to/fastpace/packages/fp

fastpace verify reports legacy_format

Your audit log was written by a pre-0.5.0 fastpace install (plain JSONL, no chain). Upgrade in place: 

fastpace audit migrate

Full runbook: Audit migration.

fastpace verify reports chain BROKEN

Some entry has been edited or the file was concatenated. Don't touch anything. The audit log is meant to be tamper-evident; breaking the chain is the signal you'd want.

  1. Capture the failure context: FASTPACE_DEBUG=1 fastpace verify > verify.log 2>&1.
  2. If you have audit replication running, the immutable copy is your source of truth — restore from it.
  3. Otherwise, email verify.log to security@fastpace.net.

Hooks not firing

Check that the hook is enabled in fastpace.config.yaml: 

hooks:
  audit_logger: { enabled: true }
  prompt_redactor: { enabled: true }
  agent_scope_guard: { enabled: true }
  runtime_guard: { enabled: true }

Then verify the runtime is invoking them. For Claude Code, check .claude/settings.json contains the hooks array.

Bypass: setting FASTPACE_NO_HOOKS=1 in your environment skips every fastpace hook. The bypass is logged to the audit chain on next call so post-hoc review can find it.

Identity rotation

Rotating your F0.1 install identity archives the prior key under ~/.fastpace/identity/archive/. New entries sign with the new key; old entries are still verifiable because fastpace verify tries every archived key. 

fastpace identity rotate
fastpace verify    # confirms historical entries still verify

Air-gapped install fails with Node.js not found

The bundle requires Node 18+ pre-installed on the host. We deliberately don't bundle Node to keep the bundle small + avoid cross-arch headaches. Install Node via your package manager / sneakernet first, then re-run ./install-offline.sh. See Air-gapped install.

SAST hook blocking git push

The F2.13 SAST/lint hook ran your configured tools and found a blocking finding. View the report: 

fastpace sast list
fastpace sast show fastpace/sast/<timestamp>.json

Three options:

  1. Fix the finding (recommended).
  2. Time-box an exception: fastpace exception request --tool Bash --reason "fix in follow-up" --ttl 60 --risk-tier medium.
  3. Tune the threshold (only for known false positives): set hooks.sast_required.block_on: critical in fastpace.config.yaml.

Reporting an issue