Troubleshooting

sandbox srt requested but not found#

ohx: sandbox `srt` requested but not found (set OHX_SRT)

srt is not on PATH. Install it with npm install -g @anthropic-ai/sandbox-runtime@0.0.77, or set OHX_SRT to its path. This is a usage error, exit code 2. --sandbox auto would run without the sandbox instead, and the report says the checks ran without isolation.

The suite could not run when locking#

ohx: the 'tests' suite could not run (<outcome>): ... No module named ...
ohx: checks run with /usr/bin/python3. If that is not the interpreter with your test dependencies, set it in ohx.toml (python = ".venv/bin/python") and run `ohx init --lock-tests` again.

OpenHarnX used an interpreter without pytest or your dependencies. Set python in ohx.toml to the one that has them, and lock again.

not inside a git repository#

ohx init, ohx hook install and ohx gate need a git repository, and exit with code 2 outside one. ohx init --lock-tests also needs at least one commit.

UNKNOWN on a check that works by hand#

The check could not give a result: missing, crashed, timed out, or its environment changed. Read the check's output linked in the brief.

• Timed out: raise timeout_s on the check, or suite_timeout_s for whole suites. Under the sandbox on a CI runner a suite can be several times slower than locally.
• A module is missing: the checker's interpreter lacks it. A {python} -m checker must be installed in the interpreter, not only present in the repository.
• The sandbox did not start: on Linux, user namespaces are needed. See the runner requirements in GitLab CI.

INVALID after updating a package#

Without environment = "uv", the interpreter's environment is fingerprinted when the contract is accepted. Installing or updating a package afterwards makes every check invalid, and the report names the files. If the change was yours, accept the contract again (ohx init --lock-tests, or a new revision). To avoid this, use environment = "uv".

BLOCKED on a test change you meant#

Review it, then lock again locally (ohx init --lock-tests) or approve it in CI. See approve intentional test changes.

STALE right after verifying#

Something changed the files after verification: an editor's autosave, a formatter, a build step that writes into the repository, or the agent itself. Run ohx verify again after everything has finished writing. Make checks keep their caches in {tmp} or turn caches off, so they never write into the candidate.

The Claude Code hook seems silent#

• ohx hook install writes .claude/settings.local.json in the repository root. Start Claude Code from that repository.
• Without a contract, the hook says "nothing verified, this repository has no contract yet". Run ohx init --lock-tests.
• With claude -p, hook messages appear only with --output-format stream-json. ohx report always has the result.
• Claude Code older than 2.1.163 shows a blocked result as a hook error instead of feedback to the agent.

The sandbox fails to start on macOS#

srt uses a Unix socket whose path must stay under about 104 characters on macOS. A very long TMPDIR can push it over. Try again with TMPDIR=/tmp.

A slow suite#

Run it in parallel with pytest_args = ["-n", "auto"] in ohx.toml, with pytest-xdist installed in the checker's environment. Per-test results still decide.

Still stuck#

Run ohx doctor and ohx --version, then open an issue with the version, platform, test runner and the report (ohx report --json). A wrong verdict is the most useful report. Security problems go through private vulnerability reporting.