Troubleshooting¶

Start here when something fails. Prefer runtime config validate before anything else — it is read-only and reports the usual causes.

runtime config validate

Binary not found / wrong version¶

which runtime
runtime version

Re-install from Installation. On macOS, clear quarantine if the OS refuses to run a downloaded binary:

xattr -d com.apple.quarantine "$(which runtime)" 2>/dev/null || true

Auth failures¶

Symptom	Check
`github` auth fails	`RUNTIME_GITHUB_TOKEN` set? Classic/fine-grained PAT with needed scopes?
`runtime auth status` shows disabled	`authentication.<provider>.enabled: true` in `config.yaml`
GCP / kubectl / oc fail	Platform CLI login done? Matching auth block enabled?

See Authentication.

runtime auth status
runtime auth login github

Policy denials¶

Denials are expected behaviour, not crashes. Confirm in the audit log:

runtime audit tail -n 20

Symptom	Check
`command run X` denied	Is `X` in `allowed_binaries`? Hard-denied in `denied_binaries`? Matching `command_policy.rules`?
Provider op denied	`providers.<name>.enabled`? A `denied:` prefix matching the op?
Worked on another machine	Different user-owned `policy-config.yaml` — upgrade trap

Capability validate fails¶

runtime capability validate path/or/name

Common causes:

Typo in operation name — compare with runtime <provider> --help
Missing required --input
Capability written for a newer/older binary — upgrade or adjust steps
Used transport: (not allowed) or both provider: and binary: on one step

Capability execute fails mid-workflow¶

Each step uses the same lifecycle as a direct command. Re-run the failing operation alone, then check audit:

runtime --output json capability execute … 
runtime audit tail --output json -n 10

Wrong org / project / namespace¶

runtime context show
runtime context use <name>

Operations that fall back to context (e.g. github repo list) use the active context only when you omit an explicit argument. See Runtime Context.

CI: cannot download release¶

While engineering-runtime-releases is private:

RUNTIME_GITHUB_TOKEN must have contents:read on that repo
Do not use github.token for the download step
Pass the secret into setup-runtime as runtime_github_token

See CI/CD.

CI: Bootstrap polluted the repo¶

RUNTIME_CAPABILITIES_DIR pointed at a tracked folder. Point it at a clone of the capability registry, or execute capabilities by full path and leave the variable unset. Details: CI/CD job contract.

AI agent runs `gh` / `kubectl` directly¶

Hooks are not loaded. Open the engineering-runtime-ai-agent repo (or install its Cursor/Claude hooks), confirm Cursor Settings → Hooks, restart the IDE if needed. See AI agent.

Specs / commands look wrong after upgrade¶

They refresh on the first command after replacing the binary. If they still disagree with runtime <provider> --help, you may be looking at a different Home:

echo "${ENGINEERING_RUNTIME_HOME:-$HOME/.engineering-runtime}"
runtime bootstrap --output json

Still stuck¶

runtime config validate
runtime audit tail -n 50
Compare with a throwaway Home (local sandbox)
Check release notes for surface changes