Skip to content

Troubleshoot the stack

Start with oakgreen doctor. Each failing line names its fix.

Symptom Fix
oakgreen: <tool> not found (exit 127) npm install -g oakgreen brings every tool.
graft doctor fails on App credentials or installation The App is not created or not installed on this repository. See Set up graft on a repository.
! labels on <repo>: … from oakgreen setup The App lacks Issues: write or is not installed there. Run graft doctor, then setup again.
cambium status: skipped: no usable cambium config The config is missing or not valid JSON. Run oakgreen setup, or fix the file it names.
cambium heartbeat: no heartbeat right after start The first tick has not finished. Wait 30 s. Still failing: read ~/.cambium/logs/cambium.launchd.err.log.
oakgreen start skips cambium No config at the default path. Run cambium install --config <file>, then oakgreen start cambium.
oakgreen start skips mycelium No source configured, or MYCELIUM_REPO missing from ~/.mycelium/env.
Bootstrap failed: 5: Input/output error Use oakgreen reload <service> instead of raw launchctl; it waits for the old process to exit.
oakgreen services shows nothing useful on Linux or Windows Services are macOS only. graft, canker and deadwood still work.
Symptom Fix
Workers fail with claude: command not found The agent captured PATH before Claude Code was installed. Run cambium install, then oakgreen reload cambium.
Every task fails and none go to q:human The base branch is red; cambium waits for it to go green. Look for the issue labelled red-base.
A repository’s tasks never start Its base reads red because no ci check runs on it. Set "requiredCheck": null, or the real check name, on its repos[] entry.
A task is requeued as spawn-failed The worktree’s install, hydrate or prepare step failed. The stderr tail is in the issue’s state comment and the worker’s err.log.
q:intake issues are never triaged Triage needs "engine": "graph" and phases.dispatch.cap above 0.
Symptom Fix
curl …:4318/v1/traces is refused otelcol is not running. Check oakgreen services otelcol and ~/.cambium/otel/otelcol.log; often otelcol-contrib is not in /opt/homebrew/bin or /usr/local/bin.
No traces in canopy cambium’s agent lost OTEL_EXPORTER_OTLP_ENDPOINT (reinstalled?), or engine is legacy, which is not traced. See Set up tracing.

Every refusal happens before anything reaches GitHub and ends with the next command to run. What each one means: graft refusals.