Troubleshooting

This is the page to consult when something goes wrong. Issues are grouped by the surface where they show up.

grith exec issues

Ptrace permission denied

$ grith exec -- bash
Error: failed to attach ptrace: Operation not permitted (os error 1)

Cause: kernel.yama.ptrace_scope is set higher than grith expects. Default distros use 1 (descendants only, what grith needs). Some hardened images (some EC2 AMIs, Ubuntu hardening guides) use 2 (admin only).

Fix:

sudo sysctl kernel.yama.ptrace_scope=1

Persist by adding to /etc/sysctl.d/. If your security policy forbids ptrace_scope < 2, you can either run grith as a user with CAP_SYS_PTRACE or use grith's setcap binary wrapper (bin/grith-setcap).

Agent hangs forever after grith exec

The supervised agent is frozen waiting for a digest decision. Check:

grith digest list

If items exist, review them:

grith digest review

If no items but the agent still hangs: the daemon may have crashed mid-call. grith daemon status to verify.

"grith: command not found" after install

The installer puts the binary in ~/.local/bin, which may not be on PATH. Add to your shell rc:

export PATH="$HOME/.local/bin:$PATH"

Or move the binary to /usr/local/bin.

Daemon issues

"Address already in use" on grith daemon start

Something else is using port 3141. Either:

ss -tlnp | grep 3141       # find the culprit

Or move grith to a different port:

grith config set server.port 3142
grith daemon start

Dashboard returns 404 for all docs paths

The daemon serves the dashboard at / and the API at the same origin. There's no path conflict in normal use. If you see 404s for the dashboard SPA routes, likely the dashboard_dir config points at the wrong location — see [server] config.

Daemon won't stop cleanly

grith daemon stop --force

Sends SIGKILL. Use only if grith daemon stop hangs for >30s.

Digest issues

Digest items keep timing out (auto-denying)

proxy.review_timeout_seconds is 300s (5 minutes) by default. If you can't review that fast, raise it:

grith config set proxy.review_timeout_seconds 1800

(Avoid disabling entirely — frozen processes accumulate.)

"Item already resolved" when approving

Another reviewer (or the timeout) got there first. Refresh grith digest list to see the current state.

Approve buttons in Slack do nothing

The HMAC callback isn't reaching grith. Check:

1. The webhook URL Slack is using points at your daemon's public address.
2. The HMAC secret in the Slack channel config matches the daemon's expectation.
3. The daemon log shows the callback hitting. If you see signature failures, the secret's wrong.

See Notification security.

Filter issues

Too much in the queue, too often

Three things to try, in order:

1. Tune proxy.auto_allow_threshold upward — see Tuning scoring thresholds.
2. Add routine entries to your profile — see Profile audit to find what's chronically escaping.
3. Let reputation accumulate. After a week of approvals, similar calls auto-allow. Especially with learn (the l key in the digest).

Calls auto-allowed that shouldn't be

The opposite problem. Check:

grith audit | grep allow | head

Look for shapes that should have queued. Common causes:

• A too-broad routine path in the profile. Tighten.
• Stale reputation. grith reputation reset --profile <name>.
• Threshold too high. Lower proxy.auto_allow_threshold.

A specific filter is firing wrong

grith proxy test '<the-call-json>'

Shows per-filter contributions. If filter X is contributing more than expected, check its config file (see Filter config files).

Build / install issues

cargo build fails on macOS or Windows

v0.1 builds only on Linux. Use the Docker option or a Linux VM for now; native macOS and Windows ship in v2.0. See the roadmap.

npm run gen:references errors

This script runs in the docs repo and shells out to the grith repo. Check:

• ../grith/ exists and is a valid grith checkout.
• cargo is on PATH.

Getting help

• GitHub Discussions — for questions and "is this a bug".
• GitHub Issues — for confirmed bugs and feature requests.
• Responsible disclosure — for security issues, please use the disclosed contact, not public issues.