Skip to content

Deployment errors

A deployment error identifies a rejected request or a failed runtime stage. Read the response with the repository, selected source, manifest, and local HTTP result.

Request failures

Category First inspection
Invalid request Repository origin, selected source, and manifest shape.
Repository access The Forge GitHub App install, grant and association for the repository named by the origin.
Runtime failure Build output, startup command, port binding, and readiness route.
Route failure The deployment result and the app exposure declaration.

Refusal codes

A refused aegis forge deploy prints a code. Read the code first, then the exit status; the number alone does not name the cause.

Code Exit First inspection
forge_intent_invalid 64 Whether the resolved repository, ref or commit values were incomplete or malformed.
forge_source_unavailable 64 Whether --repo, --ref or --sha resolves to a committed tree, and whether that tree has a readable mithran.yaml.
forge_intent_drift 1 Whether the selected source changed between request and send.
forge_preflight_unsupported 1 Whether this repository or app shape is supported by the service.
forge_preflight_refused 1 Whether the GitHub App is installed, granted and associated for this profile, agent and repository.
forge_preflight_stale 1 Whether the selected commit is still the one the service expects.
forge_result_unsupported 1 Whether the service returned a result this CLI can represent.
forge_result_binding_mismatch 1 Whether the returned result belongs to this request.

Combining --ref and --sha is refused earlier, by the parser, with exit 2. forge_preflight_refused also covers a service-side refusal, so treat it as "the request was not accepted" and work through Connect GitHub before changing permissions. With --json the refusal prints a value-free envelope on stdout and still exits nonzero.

Retry boundary

Do not retry a request until you know whether the failure came from source, configuration, build, runtime, or route handling. Keep the selected commit with the report.

Scope

This page contains no endpoint, token, or unsupported CLI instructions. The supported customer surface has one deployment operation and no separate error-inspection command.