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.
Binary not found / wrong version¶
Re-install from Installation. On macOS, clear quarantine if the OS refuses to run a downloaded binary:
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.
Policy denials¶
Denials are expected behaviour, not crashes. Confirm in the audit log:
| 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¶
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 bothprovider:andbinary:on one step
Capability authoring is not ready¶
| 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¶
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:
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_backis restored,not_committedwas untouched, andunknownrequires 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:
Still stuck¶
engrt config validateengrt audit tail -n 50- Compare with a throwaway Home (local sandbox)
- 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.