Skip to content

Troubleshooting

v0.9.9 source failures are intentional refusals, not requests to try another ambient identity. Check explicit authentication.*.source, the admitted credential-file path or named GSA, and compatible gcloud Python on Runtime's PATH. For in_cluster, check the Service IP/port and projected CA/namespace/token mount; do not copy a developer kubeconfig into the pod. Keep Runtime policy denial, native auth failure, Kubernetes RBAC refusal and a received GCP HTTP 403 separate.

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

engrt config validate

Binary not found / wrong version

which engrt
engrt version

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

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

Auth failures

Symptom Check
github auth fails ENGRT_GITHUB_TOKEN set? Classic/fine-grained PAT with needed scopes?
engrt 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.

engrt auth status
engrt auth login github

Policy denials

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

engrt 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

engrt capability validate path/or/name

Common causes:

  • Typo in operation name — compare with engrt <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

engrt --output json capability authoring-context
Reported condition Fix
No capabilities directory configured Set ENGRT_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 ENGRT_CAPABILITIES_DIR is authoritative since 0.9.2; fix its reported OS path or permission problem and write there normally.

Capability plan is denied

engrt 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:

engrt --output json capability execute …
engrt 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

engrt 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

If you have trouble accessing the release or installation artifacts, please contact the Engineering Runtime project. v0.9.9 supports macOS/Linux amd64 and arm64. Windows support is not yet available in this release.

Symptom Action
Checksum mismatch Stop; obtain a verified copy and do not install the mismatched file
Checksum tool reports unrelated missing archives Verify only the matching entry for the archive you obtained
runtime: command not found Put the chosen install directory on PATH
engrt version reports an older version Inspect command -v engrt and resolve the PATH conflict
tar cannot find ./engrt The executable is inside the archive's versioned directory

See Installation.

CI: the wrong capability source wins

Since 0.9.2, ENGRT_CAPABILITIES_DIR is authoritative and reported as capabilities-dir. If CI resolves a different definition, inspect engrt --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:

engrt config validate     # the Portal: line names the source and version
engrt 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):

engrt portal status                     # is it even pointed somewhere reachable?
export ENGRT_PORTAL_TIMEOUT_SECONDS=1   # lower the bound
unset ENGRT_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 ENGRT_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 ENGRT_PORTAL_PATH_PREFIX=/api/v1
export ENGRT_PORTAL_API_KEY='<show-once-runtime-key>'
curl -sS "$ENGRT_PORTAL_BASE_URL/health"
engrt portal status
engrt portal register
engrt 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 engrt <provider> --help, you may be looking at a different Home:

echo "${ENGRT_HOME:-$HOME/.engrt}"
engrt bootstrap --output json

Still stuck

  1. engrt config validate
  2. engrt audit tail -n 50
  3. Compare with a throwaway Home (local sandbox)
  4. Check release notes for surface changes

Windows in v0.10.0

v0.10.0 uses engrt.exe and ENGRT_*; v0.9.9 Windows remains unsupported. Match the ZIP architecture to native Windows, verify its checksum before extraction, and use Get-Command engrt -All to resolve a PATH mismatch. See Windows installation preparation.

Generic Command Engine tools must be admitted native executables. A .cmd or .bat launcher does not become trusted by adding it to an allow-list. The admitted Google Cloud SDK path uses its compatible Python/script binding; it is not a general shell-wrapper exception. Keep native authentication in the selected tool and do not broaden inherited environment to work around a refusal. Windows Home privacy uses owner/ACL checks; Unix mode bits alone cannot repair a Windows ACL refusal. v0.10.0 archives passed native Windows amd64 and arm64 qualification.

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