Runner troubleshooting
Start on the project's Slices view. Filter to failed, open the slice, and read the runner error, import error, exit code, and report count.
Setup says the project is not ready
A new Cloud project should not hit these. Setup (and the dashboard) seed both profiles and enable xai/grok-4.6. A blocker means something was later removed, or the project predates that provisioning.
Run thespider-agent status from the checkout. It reports the same sentences as this table.
| Code | Meaning | Fix |
|---|---|---|
profile_not_found | That profile does not exist (a 404). | Use security or bugs. |
config_missing | No methodology version. | Re-save the default profile, or author a version. |
no_buckets / no_passes | Methodology has nothing to run. | Publish a version with at least one of each. |
no_enabled_models | Nothing to claim. | thespider-agent setup --model <lab/model> enables one. |
empty_matrix | Buckets × passes × models is zero. | Widen scope or enable a model. |
Readiness is server state. Local CLI / login problems show up separately in check-models.
409 prompt_hash mismatch
The result's hash does not match the prompt that was claimed. Something rewrote the prompt.
Discard it, claim again, and pass {prompt_path} through unchanged. Do not invent a hash and retry.
413 output too large
Stdout or stderr exceeded the server cap (default 10 MiB). Ask the model for concise findings, keep transcripts off stdout, and try --redact (caps stdout at 1 MiB). Then claim again. A rejected payload is not imported.
Lease expired while the model was running
The slice went back on the queue, or two workers ran it. Heartbeats got lost, or timeout_seconds was too low.
Raise the timeout, keep the agent online, and let the original worker submit. A late result still wins if nobody else finished the slice. If someone else already won, you get 202 and the extra output is stored, not imported twice.
Daemon cannot clone
The daemon shells out to git. It does not manage forge credentials.
git ls-remote REPOSITORY_URLas the daemon's OS user.- SSH: right key in
ssh-agent, host key trusted. - HTTPS: credential helper (or a token URL you do not store in TheSpider).
- Confirm the campaign has a remote URL and a commit.
Managed checkouts live under ~/.local/share/thespider/checkouts unless you pass --workdir.
Slice failed, or campaign coverage looks too high
A missing marker, unclosed marker, empty marker body, malformed JSON, a value that is not an array of objects, or a nonzero runner exit used to complete the slice. It no longer does: the server returns 422, the slice is failed and claimable again, and thespider-agent increments failed and exits 1.
A valid empty array ([]) is still successful coverage — that slice really found nothing.
Retries are bounded. A slice is offered at most three times (MAX_SLICE_ATTEMPTS); after that it stays failed but is left alone, so a permanently-broken binding cannot loop run or daemon forever on the same paid model call. The campaign then reaches a terminal status and the gate a verdict — degraded, never clean. repair gives such a slice a fresh budget once you have fixed the cause.
Historic campaigns that already stored those invalid completions stay wrong until you repair them:
thespider-agent repair --campaign ID --dry-run # exits 1 when there is something to repair
thespider-agent repair --campaign ID
Then run again. --dry-run shows valid / invalid / unverified without changing anything, and exits 1 when invalid > 0 so it works as a CI check — under set -e, run the two commands separately or guard the first with || true. Valid empty-array slices are not requeued.
Repair also takes back what an invalid run produced: its reports are deleted, and a finding left with no report behind it goes too. A finding you have triaged, fixed or dismissed is never deleted — it is reported as stranded so you can decide.
OpenCode returns early or keeps a session
Usually a timeout or a stream that never closed the marker block.
Use the recovery command printed to stderr (it reads the retained session). Raise OPENCODE_CAPTURE_TIMEOUT but keep it below the model timeout. Confirm occtl can reach the OpenCode host.
Network, 429, 5xx
The first-party agent retries those with backoff. It does not retry 409 or 413. If retries keep going, check /healthz, the token, and that it is scoped to this project.