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 authoring is not ready¶

runtime --output json capability authoring-context

Reported condition	Fix
No capabilities directory configured	Set `RUNTIME_CAPABILITIES_DIR`, or add a `capabilities.sources` entry
Several directories configured, none named	Name the one you author into with `capabilities.authoring_source`; Runtime asks rather than guessing where your work lands
Unknown or duplicate source name	Make the selected name match exactly one source
Selected source directory is relative	Use an absolute path
Selected source does not exist	Create or check out that directory explicitly; Runtime never fetches or creates it
Directory exists but is not writable	Fix ownership or permissions. Since 0.9.2 this is an OS question — authoring does not require a `file_policy.write_roots` grant

Never work around these errors by writing to the unset fallback under <Runtime Home>/capabilities. A directory explicitly named by RUNTIME_CAPABILITIES_DIR is authoritative since 0.9.2; fix its reported OS path or permission problem and write there normally.

Capability plan is denied¶

runtime capability plan path/or/name --input key=value

Plan reports every denied step and exits non-zero without authentication, execution, mutation or audit. Supply missing required inputs, then review the resolved operation, context, File Engine grant, compiled safety decision and declarative policy result. Identity allow-list evaluation is deferred until execution; all other displayed checks must be allowed. A clean plan still does not authorize execution.

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

Structured file edit is refused¶

selected no files / zero matches — correct or narrow the selector; use expected-count flags to state the reviewed estate shape.
expected N, found M — nothing was written. File Engine preflights the entire batch before its first replacement.
content/identity changed after preflight — another process modified the target during this invocation. Review the new bytes and run again.
partial commit recovery — inspect the returned per-file states and audit file_batch. rolled_back is restored, not_committed was untouched, and unknown requires manual inspection.
capability preview refused before step 1 — a mutating step has no registered preview contract. Split it from the preview workflow or add a typed provider preview operation.

Wrong org / project / namespace¶

runtime context show
kubectl config use-context <name>   # or: oc project <name> / gcloud config set project <id>

Runtime observes the selected tool's own native context. For gh repo list, that is an explicit owner when supplied, otherwise the authenticated GitHub CLI account and host. Runtime has no independent context to switch. See Runtime Context.

Cannot download the release¶

The release artifacts are public — no token is involved, so authentication is never the cause. Work through these instead:

Symptom	Cause	Fix
`install.sh` exits 2	Unsupported OS or architecture	Supported: macOS and Linux on `amd64`/`arm64`. On Windows, download the `.zip` manually
`install.sh` exits 4	The tag or asset does not exist	Check the latest release. A pinned `VERSION=` that was never published fails here
`install.sh` exits 5	Checksum mismatch — nothing was installed	Retry once; a truncated download is the usual cause. If it repeats, report it and do not use the file
`install.sh` exits 6	No writable install directory	Set `INSTALL_DIR=` to somewhere on your `PATH`, or create `~/.local/bin`
`shasum -c` reports 5 failures	Missing `--ignore-missing`	`SHA256SUMS.txt` covers all six archives. Add `--ignore-missing` — the five you did not download are not failures
`runtime: command not found` after install	The install directory is not on `PATH`	The installer prints which directory it used and warns when it is not on `PATH`
Homebrew installs successfully but `runtime version` is old	A manual install (often `~/.local/bin/runtime` or `/usr/local/bin/runtime`) appears before Homebrew on `PATH`	Follow If another runtime wins on PATH to compare both binaries and safely prefer Homebrew
`brew install` cannot find the package	The custom tap is not selected	Run the fully qualified command: `brew install engineeringruntime/tap/engineering-runtime`
`brew upgrade engineering-runtime` says it is already installed but the formula is stale	Local Homebrew metadata has not refreshed	Run `brew update`, then `brew upgrade engineering-runtime`; verify with `$(brew --prefix)/bin/runtime version`
`tar: ... Not found in archive`	Assuming a bare `./runtime`	The archive expands to a versioned directory; the binary is inside it

See Installation and CI/CD.

CI: the wrong capability source wins¶

Since 0.9.2, RUNTIME_CAPABILITIES_DIR is authoritative and reported as capabilities-dir. If CI resolves a different definition, inspect runtime --output json capability list, remove unintended competing sources, or select the intended named source with capabilities.authoring_source. Pin the checkout revision independently; Runtime records file digests but does not fetch Git revisions. Details: Sharing a Capability Source.

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

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

Policy changed and nobody edited it¶

If rules moved without a local edit, check whether a control plane published them:

runtime config validate     # the Portal: line names the source and version
runtime audit tail -n 50    # look for command=portal.sync

Successful Enterprise registration permanently selects the signed managed generation for that Runtime Home. Every sync is audited, so the log tells you when a new atomic policy/config version landed. Turning Portal networking off does not restore local authority.

The first command is slower after enabling the portal¶

Runtime attempts heartbeat at most once per CLI process. An unreachable Control Plane may therefore cost one configured timeout (default 5s):

runtime portal status                     # is it even pointed somewhere reachable?
export RUNTIME_PORTAL_TIMEOUT_SECONDS=1   # lower the bound
unset RUNTIME_PORTAL_ENABLED              # or turn it off entirely

The command and its local audit record still succeed; only fleet freshness is lost. Explicit registration/sync commands do report network failure.

`portal register` or `portal sync` fails¶

Point RUNTIME_PORTAL_BASE_URL at your company app-api origin, not at a UI or the public static API reference. Use only /api/v1 and provide the show-once key:

export RUNTIME_PORTAL_PATH_PREFIX=/api/v1
export RUNTIME_PORTAL_API_KEY='<show-once-runtime-key>'
curl -sS "$RUNTIME_PORTAL_BASE_URL/health"
runtime portal status
runtime portal register
runtime portal sync

Wrong origin/prefix produces authentication, HTML, or 404 errors. Failed first registration leaves local authority untouched. After enrollment, a failed sync preserves the last verified generation. See Control Plane (Portal).

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 "${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

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.