Docs Local development

Troubleshooting

The most common things that break, and the shortest path out of each one.

If gridtrue validate is unhappy, the problem is almost always one of five things. Run through this list before filing a bug.

gridtrue: command not found

The installer drops the binary into /usr/local/bin (macOS / Linux) or %USERPROFILE%\AppData\Local\Programs\gridtrue (Windows). Make sure that directory is on your PATH, then restart your shell. On Linux, systems that use /opt may need a symlink.

Cannot connect to daemon

bash

gridtrue daemon status
# If it prints 'not running':
gridtrue daemon start
# If it prints 'stale socket':
gridtrue daemon stop && gridtrue daemon start

Keyring unavailable

Headless Linux boxes without a running secret service (gnome-keyring, kwallet) will fail at login. Install libsecret and a backend, or fall back to the file-backed keyring with GRIDTRUE_KEYRING=file. The file backend is encrypted with a passphrase you enter on each unlock.

Validation fails with 'runtime not found'

The step references a runtime id that is not declared in .gridtrue/validate.yaml, or declares a native sdk that is not installed. Run gridtrue sdk list to check, then gridtrue sdk install <name> for missing ones.

Policy rejects the push

Exit code 3 means the network accepted the connection but refused the push — usually because required attestations are missing. Run gridtrue status to see which predicates are missing, then gridtrue validate --profile=pre-push to generate them.

Getting help

gridtrue doctor prints a structured diagnostic (binary version, daemon status, keyring, network). Paste the output when filing an issue.
gridtrue <verb> --help is always authoritative — the docs may lag by a release.
Community forum at https://gridtrue.io/community for questions. Bug reports at https://gridtrue.io/issues.