Troubleshooting and FAQ

Troubleshooting and FAQ

The sandbox says host directories are not visible to the engine

Your engine runs in a virtual machine that does not share the path in question. Colima shares your home directory by default; Docker Desktop shares configured paths. Keep the data directory and the repository under a shared path. The probe exists so that this fails loudly instead of validating an empty directory.

The image is not present

Pull the pinned toolchain image once with network access: docker pull golang@sha256:... from the table in Configuration, or pass -pull. Runs never pull on their own.

The repository is unsupported

inspect lists refusals. Common ones: a vendor/ directory, go.work, .gitmodules, a nested go.mod, cgo, a replace to a local path, a go directive with no pinned image, tracked symlinks. Each is refused rather than partially supported.

The baseline is failing

A test fails before any change, so no upgrade is attempted and no model is called. Fix or skip the test in the repository first. This is deliberate: an upgrade cannot be validated against code that does not pass.

The upgrade regressed and the run ended

In baseline mode that is expected for any upgrade that needs a repair. Use model mode.

The run ended acquisition_failed with exit code 6

The module proxy or checksum database was unreachable or failed (DNS, connection, timeout, TLS, or a 5xx answer) while the toolchain fetched the upgrade; the toolchain's message is in the result. It says nothing about the upgrade itself, and a later run may succeed. Check your network or proxy and run again.

The run paused with exit code 5

An approval is pending. runs show <id> shows its presentation; approve or reject, then resume.

I approved a run and want to close it instead

reject only works on a pending approval. Use repo-steward cancel <run-id>; the run ends as cancelled and nothing is executed or pushed.

A version I expected is listed as ineligible

The version cooldown: a version published less than -min-age ago (72 hours by default), or one the module proxy gives no publish time for, is ineligible and its candidate entry says why. Pass -min-age 0 to turn it off, or wait. In -select vulnerable the version that clears an advisory is exempt.

vulns exits 4, or maintain -select vulnerable does not propose anything

vulns exits 4 when third-party findings are present; that is the report, not a failure. For maintain, the outcome says why: scan_inconclusive (the scan did not complete cleanly; the reason is given, and it is never read as "no vulnerabilities"), no_vulnerabilities (nothing in third-party dependencies; standard-library findings are listed but not acted on), no_fix_available (no eligible version clears any finding; a reason per finding is given), or regressed (the upgrade that clears the advisory breaks the build, which the deterministic pipeline cannot repair). A scan that exits 3 is inconclusive; read the reason in the report.

Standard-library findings are reported but never fixed

They follow the Go version of the toolchain image, and Repo Steward never changes the go directive. vulns lists them for information and still exits 0 if they are the only findings.

The scanner or the database fails verification

Before every scan the scanner's sha256 and build information and the database's content hash and modified time are checked on the host. A mismatch is an error and nothing is scanned or rebuilt. Remove the scanner's directory under tools/ in the data directory to rebuild it, or the database's under vulndb/ to fetch it again.

The data directory is refused as insecure

The data directory must be owner-only. One that group or others can write, or that another account owns, is refused with a message naming the path, its mode, and the fix; one they can only read or enter is tightened to 0700.

Resume says it needs -fixture-proxy

The run started with a fixture proxy and must continue under the same configuration; pass the same directory.

The model produced no tool call, or the server rejected its output

Local models sometimes narrate instead of acting or emit a malformed tool call. A reply with no executable tool call is recorded as an invalid decision and nudged on the next step, so it costs one step and appears in runs show; three such steps in a row end the run on the consecutive-failure limit. The runtime retries transient server errors with backoff and records every attempt; the run ends with model_unavailable or goal_failed and no claim. The benchmarks report how often this happens per model.

A recording no longer replays

Recordings are keyed by the exact request. Any change to the system prompt, a tool description or schema, or a tool result shape invalidates them. Re-record with -record.

Deleting the data directory fails with permission errors

The Go toolchain creates the module cache read-only. chmod -R u+w the directory first.

Two processes on the same run

The second is refused by the lock. A suspended process still holds its lock; there is no takeover.

Does it ever modify my checkout?

No. The checkout is read once, at clone time, and never written. Every benchmark run asserts this.

Does it ever push without asking?

No. Publication requires -publish, a verified destination, and an explicit approval bound by hash to the frozen proposal.

Does it send my code to a model?

In model mode, tool results such as file contents and compiler output are sent to the configured model. Only local Ollama models are wired in. See Data and Privacy.