Troubleshooting

This page is organized by failure mode. Find the shape that matches your problem, read the cause, apply the fix. Most failures pair a process exit code with a machine-friendly errors[0].code; route on the exit code first, then on the code. The full catalog is in Understanding Results -> errors[].code catalog.

Examples use the canonical calc project (a small Python package) and Nove Test 0.1.2.

✗ <command>
  <code>: <human-readable message>

err  = envelope["errors"][0] if envelope["errors"] else None
code = err and err["code"]
# install hints for engine errors live in data.engine_readiness.issues[],
# NOT in err["details"].

Exit codes at a glance

Install issues

command not found: novetest

The install script drops the binary at ~/.local/bin/novetest (POSIX) or %USERPROFILE%\.local\bin\novetest.exe (Windows), which may not be on PATH.

Fix. Add it:

# Linux / macOS — add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Windows — add to PowerShell profile
$env:PATH = "$HOME\.local\bin;$env:PATH"

Re-check with novetest --version (novetest 0.1.2 (Python …)).

Linux: version 'GLIBC_2.xx' not found

The install succeeded — SHA-256 verified, binary written — but every novetest invocation dies instantly, before any output, with a dynamic-loader error:

novetest: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.39' not found
  (required by /home/you/.local/bin/novetest)

(The version number in the error names whichever glibc symbol your installed binary needs — you may see a different number than 2.39; see the table below.)

Cause. The Linux binaries of every release up to and including 0.2.1 are PyApp bundles built against glibc 2.39, so they need a host glibc >= 2.39. From v0.3.0, that floor is much lower — glibc >= 2.31 (a CI-enforced ceiling; the v0.3.0 binary as shipped in fact requires only GLIBC_2.30). Downgrading never helps on either side of that line: every release before v0.3.0 carries the 2.39 floor or higher. Nothing is wrong with your download either: the failure happens in the loader, before the process starts, so it costs milliseconds and produces no novetest/v1 envelope at all. Each release states its own minimum in its release notes; check those for the version you are installing.

Check your host's glibc:

ldd --version | head -1     # e.g. "ldd (Debian GLIBC 2.36-9+deb12u14) 2.36"

Then compare against the two floors:

Fix — upgrade to the current release first. If you installed before v0.3.0, re-running the install one-liner overwrites the binary in place and very likely fixes this on its own — most hosts the old 2.39 floor excluded are inside the new 2.31 one:

curl -fsSL https://ailovestesting.com/products/novetest/install.sh | sh
novetest --version

Still below the floor? Install from PyPI instead. The Python-tooling install (see Installation -> Other ways to install) runs novetest on your host's own Python instead of the CPython the binary bundles, so no binary glibc floor applies to it:

uv tool install novetest      # or: pipx install novetest
novetest --version            # expect ok: true, schema "novetest/v1"

It needs Python >= 3.11 on the host. Everything after installation — verbs, envelopes, exit codes, the Project Store — is identical either way.

Otherwise, move to a host or base image with glibc >= 2.31 (or >= 2.39 if you must stay on a release before v0.3.0).

Agents: recognize this by the fragment GLIBC_2. together with not found on a libc.so.6 line, on a novetest call that exits 1 in a few milliseconds. On a currently-blocked host, first try upgrading (re-run the install one-liner — v0.3.0+ needs only glibc >= 2.31); if that still fails, switch to the PyPI install. Do not retry the binary as-is, and do not fall back to an older release: every release before v0.3.0 carries the 2.39 floor or higher.

Install script aborts with SHA-256 mismatch

The install script downloads the binary plus its .sha256 sidecar, verifies the hash, and aborts loudly, writing nothing, on a mismatch — a real integrity guard. The download was corrupted or the release artifacts are inconsistent.

Fix.

1. Re-run the install script (usually a flaky network).
2. Pin a version: NOVETEST_INSTALL_VERSION=v0.1.2 curl … | sh.
3. Still failing? File an issue with your OS / arch / network situation.

First run is slow (5–15 seconds)

Expected. The binary is PyApp-wrapped — it unpacks its bundled CPython once, on the first invocation per binary version. Later runs are warm.

Windows: PowerShell script blocked

Your execution policy is blocking install.ps1.

Fix.

powershell -ExecutionPolicy Bypass -File install.ps1
# or
Unblock-File install.ps1; .\install.ps1

Supported platforms

Linux x86_64, Linux aarch64, macOS universal2 (one fat binary for Intel + Apple Silicon), Windows x86_64. No Windows arm64 build.

Linux hosts additionally need glibc >= 2.39 to run the binaries of releases up to and including 0.2.1 — check with ldd --version, and check each release's notes for its own minimum. From v0.3.0 that floor drops to glibc >= 2.31. Below the floor, use the PyPI install path; see the GLIBC_2.xx entry above.

init issues

store-corrupt (exit 5)

✗ init
  store-corrupt: Project Store at /home/you/calc-demo/.novetest is unreadable: <reason>.

rm -rf .novetest
novetest init

{
  "errors": [
    { "code": "store-corrupt", "details": {}, "message": "Project Store at <path> is unreadable: <reason>." }
  ]
}

init succeeded but engine readiness: engine-missing

When init recognizes your ecosystem (project markers exist) but can't find a usable engine, it still succeeds and leads with ✓ — the readiness line reports what's missing. (A directory with no recognized markers at all, or with two or more viable engines, is different: init refuses and creates nothing — see the next section.)

✓ Initialized .novetest/ at /path/to/calc-demo/.novetest
  engine readiness: engine-missing — no engine detected
  issue: Python workspace detected but no pytest configuration (pytest.ini, [tool.pytest.ini_options], conftest.py, or tests/ dir) found

{
  "command": "init",
  "data": {
    "engine_readiness": {
      "ecosystem": null, "engine": null, "engine_version": null,
      "evidence": ["pyproject.toml"],
      "issues": ["Python workspace detected but no pytest configuration (pytest.ini, [tool.pytest.ini_options], conftest.py, or tests/ dir) found"],
      "state": "engine-missing"
    }
  },
  "errors": [],
  "ok": true,
  "schema": "novetest/v1",
  "warnings": []
}

no-engine-detected (exit 4) / engine-ambiguous (exit 2) — init refused, nothing created

Two cases where init does not create a store. (Per-engine detection markers and the selection rules live in Supported Languages.)

✗ init
  no-engine-detected: No supported engine marker found at /path/to/dir; no Project Store was created. Note: candidate projects were discovered below (data.candidates); cd into the one you want and run `novetest init` there — novetest never initializes a directory you are not standing in.

✗ init
  engine-ambiguous: Multiple viable engines detected (pytest, jest); no Project Store was created. Choose one explicitly: `novetest init --engine <name>`.

novetest init --engine pytest

test / run issues

engine-missing (exit 4)

✗ run
  engine-missing: engine readiness state: engine-missing (engine=(none detected))

{
  "command": "run",
  "data": {
    "engine_readiness": {
      "ecosystem": null, "engine": null, "engine_version": null,
      "evidence": ["pyproject.toml"],
      "issues": ["Python workspace detected but no pytest configuration … found"],
      "state": "engine-missing"
    }
  },
  "errors": [
    { "code": "engine-missing", "details": {}, "message": "engine readiness state: engine-missing (engine=(none detected))" }
  ],
  "ok": false,
  "schema": "novetest/v1",
  "warnings": []
}

adapter-<kind> (exit 4)

{
  "command": "test",
  "data": {},
  "errors": [
    { "code": "adapter-unparseable-output", "details": {}, "message": "pytest-cov did not write coverage JSON to …/coverage.json; stderr tail: ERROR: file or directory not found: bogusverb\n\n" }
  ],
  "ok": false,
  "schema": "novetest/v1",
  "warnings": []
}

adapter-invalid-target (exit 2) — usage error

Exit code 3 (tests failed or errored) — NOT an error

3 recommendations · 2 categories · run_id=…

  ! [investigate_location] Investigate `subtract`@6 in `calc/arithmetic.py` (rank 1, ochiai=1.000, sbfl_per_test).

if exit_code == 3:
    assert env["ok"] is True               # DATA, not a tool error
    for rec in env["data"]["recommendations"]:
        route(rec["category"])             # 7 categories; priority int, lower = higher

Explicit target matched nothing (exit 0 — but check the counts)

not-found (exit 2) — bad run_id

✗ coverage.show
  not-found: No Memory Entry for run_id='FAKE123'

novetest memory list

{
  "command": "coverage.show",
  "data": {},
  "errors": [
    { "code": "not-found", "details": {}, "message": "No Memory Entry for run_id='FAKE123'" }
  ],
  "ok": false,
  "schema": "novetest/v1",
  "warnings": []
}

Coverage issues

✓ per-test · 13/13 statements (100.0%) · run_id=…   ← healthy
— unavailable (missing-derived-facts)               ← no coverage recorded

novetest run --coverage    # -c is the short form
# or
novetest test              # `test` ALWAYS collects coverage

"coverage_outcome": {
  "kind": "unavailable",
  "reason": "missing-derived-facts",
  "detail": "No coverage_facts.json found for this run; call derive_coverage_facts first",
  "run_reference": { … }
}

Go projects never produce coverage facts. The go-test adapter runs your tests and writes a coverage profile, but the coverage engine doesn't consume it, so --coverage on a Go project yields an unavailable coverage outcome. The other five engines (pytest, jest, cargo-test, junit, xunit) do produce coverage facts.

localization issues

✗ localization
  invalid-flag: Invalid --formula='nope'; expected one of ['dstar2', 'ochiai', 'op2', 'tarantula']

"localization_outcome": {
  "kind": "unavailable",
  "reason": "no-failed-tests",
  "detail": "run has no failed test results",
  "run_reference": { … }
}

{
  "command": "localization",
  "data": {},
  "errors": [
    { "code": "invalid-flag", "details": {}, "message": "Invalid --formula='nope'; expected one of ['dstar2', 'ochiai', 'op2', 'tarantula']" }
  ],
  "ok": false, "schema": "novetest/v1", "warnings": []
}

reset issues

confirm-required (exit 2)

✗ reset
  confirm-required: `novetest reset` is destructive. Pass --confirm to acknowledge.

novetest reset --confirm

✓ Reset .novetest/ at /path/to/.novetest
  removed: nothing
  engine readiness: ready — python/pytest 9.0.3

{
  "command": "reset",
  "data": {},
  "errors": [
    { "code": "confirm-required", "details": {}, "message": "`novetest reset` is destructive. Pass --confirm to acknowledge." }
  ],
  "ok": false, "schema": "novetest/v1", "warnings": []
}

replay issues

replay actually re-executes the run, so it can hit engine problems. A healthy replay reads ✓ reproducible · 1/1 · run_id=….

novetest replay <run_id> --reruns 3 --timeout 1200

Output-mode issues

NOVETEST_OUTPUT=ndjson novetest test

export NOVETEST_OUTPUT=json

Project Store issues

store-corrupt / store-wipe-failed (exit 5)

Two distinct corruption classes share the store-corrupt code — the message's path tells them apart:

• Store metadata — .novetest/store.json is missing, malformed, or permission-blocked (store-corrupt); or a filesystem error interrupted reset (store-wipe-failed).
• A single run record — the record.json of the exact run you addressed by run_id (memory show / memory delete / coverage show / coverage diff / regression compare / compare / localization / replay / inspect) is torn, hand-mangled, or written by a newer schema. The message names the corrupt file's absolute path. This is NOT not-found: the run exists, its storage is unreadable — re-running or picking another id will not fix it.

Scan verbs are unaffected by the record class: memory list still exits 0, skips the bad record, and attaches one corrupt-run-record-skipped warning per skip (see Understanding Results, warnings catalog).

Fix. Split by the class:

• Message path ends in store.json (or the code is store-wipe-failed): check permissions, salvage the file if you can; worst case

  bashcopy

  rm -rf .novetest
  novetest init

  You lose ALL run history but recover the store. (Agents: do NOT auto-recover — this destroys data; surface to the operator.)

• Message path ends in record.json: only that ONE run's evidence is affected — every other run stays intact and listable. memory delete cannot tombstone a corrupt record (tombstoning re-writes the parsed record), so recovery is manual: with operator approval, delete the named record.json's run_<id>/ parent directory, then re-run the tests to produce fresh evidence.

"How do I share run history with my team?"

Commit .novetest/ to git — plain JSON, diffs cleanly. Most teams choose NOT to (history is large and per-developer); do it only for a single team-shared baseline.

"How do I clean up old runs?"

novetest memory delete <run_id>   # tombstone one run
# or wipe everything:
novetest reset --confirm

Idempotency and retry policy (agent reference)

When to abort vs when to recover

Health-check pattern (agent reference)

# 1) Binary on PATH
command -v novetest >/dev/null || { echo "novetest missing"; exit 1; }

# 2) Identity envelope
NOVETEST_OUTPUT=json novetest --version | \
  jq -e '.ok == true and .schema == "novetest/v1"' \
  || { echo "version envelope malformed"; exit 1; }

# 3) Project store exists (if you have a workspace)
if [ -d ./.novetest ]; then
  NOVETEST_OUTPUT=json novetest status | \
    jq -e '.ok == true' \
    || { echo "status envelope malformed"; exit 1; }
fi

When all else fails

1. novetest --version to confirm the binary is sane.
2. novetest --help to confirm the verb exists.
3. novetest status (after init) to see what's actually stored.
4. Re-run with novetest --output json <verb>; errors[0] carries more detail than the text-mode line.
5. Search the issue tracker: https://github.com/Nove-Lab/Nove-Test/issues
6. File a new issue with the JSON envelope and your OS / engine versions.

What to read next

• Exit-code -> meaning table → Understanding Results -> Exit codes.
• Per-engine setup → Supported Languages.
• Deeper verbs → Advanced Usage.