Troubleshooting¶
Work from the command's own output and exit status. Aegis prints refusals to
stderr as aegis: <detail>. With forge deploy --json, typed structured
source and deployment refusals print a value-free envelope on stdout and exit
nonzero; configuration, account and Auth failures use stderr with empty stdout.
Invalid forge init requests also use stderr, including with --json.
Identify the failed stage before retrying.
Check the installation first¶
A version line reporting 0.9.4 means the launcher found and verified its native companion.
Other outcomes:
| What you see | Cause | Next action |
|---|---|---|
aegis: unsupported host: this launcher runs only on macOS 15+ arm64, exit 1 |
The host is not Apple Silicon on macOS 15 or newer. | Use a supported host; the launcher starts no payload here. |
aegis: macOS 15 or newer is required, exit 1 |
The macOS version is too old. | Upgrade macOS. |
aegis: native payload package @mithran-hq/aegis-darwin-arm64@0.9.4 is not installed, exit 1 |
The platform package did not install with the launcher. | Reinstall the same version: npm install --global @mithran-hq/aegis@0.9.4. |
native manifest, checksum, byte count, not executable or not a Darwin arm64 Mach-O binary, exit 1 |
The installed payload does not match the release manifest. | Remove and reinstall the same version from the public registry. Do not run a modified payload. |
command not found for aegis |
The npm global prefix is not on PATH. |
Add the npm global bin directory to PATH. Do not install with sudo. |
The launcher declares no Node.js minimum. If it fails before printing a reason, upgrade Node.js and try again; report the exact message rather than guessing a supported version.
Sign-in¶
aegis auth login prints aegis: sign-in URL: <url> to stderr and opens the
browser. The flow waits up to two minutes for the loopback callback on
127.0.0.1.
| Symptom | Meaning | Next action |
|---|---|---|
| No browser opened | The host has no usable browser, or the launch failed. | Run aegis auth login --no-browser and open the printed URL on the same machine. |
| URL opened on another computer | The callback cannot reach 127.0.0.1 on the host that ran the command. |
Open the URL on the machine running Aegis. |
Command exits 0 but prints nothing |
Expected in 0.9.4: success is silent until the confirmation added by a later release. | Run aegis auth status to confirm the session. |
| Timeout after two minutes | The browser step did not complete in the budget. | Run aegis auth login again and finish the prompts promptly. |
no bound account for this profile, exit 66 |
The profile has no stored session, or login state is incomplete. | Complete aegis auth login for that profile, then rerun the command. |
A configuration refusal, exit 64 |
The connection file, --config, --connection or state root failed validation. |
Fix the reported path or profile; see Account setup. |
If an output tells you to run auth signin, treat it as a stale 0.9.4
message: the accepted form is aegis auth login.
aegis auth status is human-readable and has no JSON form. aegis auth
logout exits 75 when it reports remote_revocation: failed and 77 when
it reports remote_revocation: refused; any other result exits 0, and the
two printed lines name which part succeeded.
Gateway¶
aegis gateway enable --agent codex needs a signed-in account and a supported
Aegis installation for its credential helper.
| Symptom | Cause | Next action |
|---|---|---|
Exit 66, no bound account for this profile |
Sign-in is missing for this profile. | Run aegis auth login, then enable again. |
Exit 64, gateway_helper_missing_identity or an unsupported helper layout |
The running Aegis executable is not in a supported installed distribution. This does not diagnose a missing Codex or Claude Code installation. | Repair the Aegis global installation with npm install --global @mithran-hq/aegis@0.9.4, then rerun aegis gateway enable --agent codex. |
Exit 64, gateway enable refused for <agent> |
A managed key already holds a different value than the gateway recorded as its own. | Restore each named key to the value in the gateway transaction backup, leaving unrelated keys untouched, then run aegis gateway disable --agent codex and re-enable. |
Exit 64, gateway disable refused for <agent> |
The same conflict blocks the restore. | Apply the same restore-first recovery, then run the disable again. |
Exit 75 |
A deadline expired, enable succeeded but its status record could not be published, or disable restored settings but cache cleanup failed. | Read the outcome and cleanup diagnostic, then inspect aegis gateway status --agent codex before choosing recovery. Enable publication failure leaves settings enabled; disable cleanup failure leaves settings restored. Follow the printed recovery rather than assuming the action was rolled back. |
Exit 77 |
Ownership remediation is required for a file the gateway will not overwrite. | Fix the reported ownership, then rerun. |
aegis gateway status --agent codex prints the managed overrides, an
aegis: engine ... line and an aegis: helper ... line. Do not edit managed
provider settings by hand; use the disable action so the gateway can restore
what it recorded. See Run agents.
Forge initialization¶
aegis forge init is local and needs no session. A refusal exits 64:
cannot unambiguously detect an existing static applicationmeans the directory has no rootindex.html, or has a competing build manifest. Writemithran.yamlfor the real runtime and rerun.- An invalid existing manifest is refused with the finding; correct the named field and rerun. Initialization never chooses a framework or rewrites source.
Forge deploy¶
| Code | Exit | Meaning | Next action |
|---|---|---|---|
forge_source_unavailable |
64 |
The selected committed source is unresolvable, or the selected commit has no readable mithran.yaml. |
Check the Git origin, the selected --repo/--ref/--sha, and that the commit contains the manifest. |
forge_intent_invalid |
64 |
The frozen deploy intent is incomplete or malformed. | Check the connection profile and repository selection; report the code if it persists. |
forge_intent_drift |
1 |
The bound deployment disagrees with the frozen intent or changed during authorization. | Rerun from the same repository and commit; report the code if it persists. |
forge_preflight_unsupported |
1 |
The service returned no supported preflight projection. | Report the code; this is not fixed by changing your source. |
forge_preflight_refused |
1 |
The service refused the authenticated preflight. | Check the four GitHub facts in Connect GitHub; the same code also covers a service-side refusal. |
forge_preflight_stale |
1 |
The accepted preflight is stale. | Rerun aegis forge deploy; the next run takes a fresh preflight. |
forge_result_unsupported |
1 |
The service returned no supported deploy result. | Report the code. |
forge_result_binding_mismatch |
1 |
The result does not match the frozen intent. | Rerun from the same repository and commit; report the code if it persists. |
Source selection is resolved before the profile is read. A
forge_source_unavailable refusal therefore appears even when you are also
signed out; fix the source first, then rerun to see the account state. A
non-GitHub origin is refused with a request to pass --repo.
Most Forge refusals exit 1, not 64. Only forge_intent_invalid and
forge_source_unavailable use 64. Read the code, not the number alone.
Diagnostics look wrong¶
In 0.9.4, aegis doctor and aegis status print this line and exit 0,
even when the journeys work:
aegis product scaffold: auth, gateway, and Forge are unavailable
The JSON forms carry
"status":"scaffold" and "journeys":"unavailable". A later release
corrects the values while keeping the keys and schema. Neither form is a
live health check; use aegis auth status and aegis gateway status --agent codex for
actual state. See CLI reference.
Exit codes¶
| Exit | Meaning |
|---|---|
0 |
Success. |
1 |
Launcher refusal, or most Forge service refusals. |
2 |
The parser refused the command line. |
64 |
Configuration or usage refusal. |
66 |
A required input is missing, such as a bound account. |
69 |
A journey or capability is unavailable in this build. |
75 |
Temporary failure; retry is safe. |
77 |
Permission refused. |
Where to look next¶
Read Deploy for request semantics, Deployment results and proof for the evidence to keep, and Support for what to include in a report. Do not invent a hosted status, URL or rollback command to work around a refusal.