18 , troubleshooting

Common problems and fixes.

Daemon will not start

Check the policy file first. If it's valid, run with debug logs to see the full error.

faramesh policy validate policy.fpl

faramesh serve \
  --policy policy.fpl \
  --log-level debug

audit tail cannot connect

Usually the daemon is not running, or the socket path is wrong. Use the same socket you passed to --socket.

faramesh audit tail \
  --socket /tmp/faramesh.sock

Lots of DEFERs, nothing executes

Your policy is requiring manual approval for these actions. Approve manually with the defer token.

faramesh agent approve <defer-token>

Denies are hard to understand

Use explain to see exactly which rule blocked the action and the reason attached to it.

faramesh explain \
  --last-deny

faramesh explain \
  --token dnl_xxxxxxxx

Chain verify fails

If violations appear, treat it as a data integrity incident and investigate immediately.

faramesh audit verify /path/to/faramesh.db

MCP gateway returns 502

The --mcp-target is down or unreachable. Test the target directly and restart with the correct URL.

eBPF not available on macOS

Expected. eBPF requires Linux kernel support. Use the SDK, proxy, or MCP adapters on macOS instead.

Auth login fails

Check the URL and connectivity to FCP.

faramesh auth login \
  --horizon-url https://your-horizon-url

faramesh auth status

Hub install or verify fails

Confirm pack reference, trust tier, and signature settings.

faramesh hub search "payment"
faramesh hub verify org/payment-guard@1.2.0 --require-signature

Compliance export fails

Ensure you pass a valid WAL path and that the daemon has produced records.

faramesh compliance export --wal /var/lib/faramesh/dpr.wal --out compliance.json