API errors¶

Use this page when a map command reaches Forge and Forge returns a non-success HTTP status. App runtime HTTP responses are different. Use the HTTP app contract, deploy status, and deploy evidence for readiness, route, and app-response failures.

Read the error¶

First decide whether the command received a Forge control-plane HTTP response. The CLI prints failed commands as map: <error>. A local validation error has no HTTP status or response body; fix the field named by the CLI before retrying. Generic control-plane API errors look like this:

map: MAP returned <http-status>: {"status":"error","code":"<code>","message":"<message>"}

--json does not remove the CLI error prefix for generic failed requests. The CLI checks the HTTP status before printing successful JSON output.

Some commands use a more specific prefix because the next action is tied to the command. The table lists the inner prefix after map:.

Prefix	Where it appears	What to do first
`MAP returned <http-status>`	Generic control-plane reads and writes, `map watch` status polls, and canary errors.	Read the HTTP status, `code`, and `message`.
`<path> returned <http-status>`	Read helpers for control-plane routes, such as `map versions` and checks that read config or route status.	Treat it like `MAP returned`: read the HTTP status and response body, then confirm the command used the intended account context.
`onboard returned <http-status>`	`map onboard` received a non-success response.	Check the repo slug, installation ref, GitHub App grant, and setup context.
`onboard conflict`	`map onboard` received a `409 Conflict` response.	Keep the redacted response body and re-check the repo slug, installation ref, account context, GitHub App grant, and project/app ref.
`version not publishable`	`map publish` receives `400 Bad Request`.	Select a reviewed deployment that reached `Succeeded` or `Promoted`.
`stale: the reviewed source moved`	`map publish` receives `409 Conflict`.	Re-run `map versions <app>`, re-check the selected version and reviewed Git commit SHA, and retry only if they still match the intended release.

Connection, response-read, and response-parse failures are not control-plane status responses:

Prefix	Meaning
`MAP request failed`	The CLI could not complete the HTTP request. Check endpoint, network, and saved login context.
`MAP watch failed`	`map watch` could not send a status poll. Check endpoint, network, and saved login context.
`onboard request failed`	`map onboard` could not send the onboarding request. Check endpoint, network, and saved login context before re-running.
`request <path> failed`	A read helper could not send a request to the named control-plane route. Check endpoint, network, and saved login context.
`read MAP response`	The CLI received a response but could not read it. Inspect current state before retrying a command that can change deploy, publish, canary, rollback, onboarding, or access state.
`read MAP watch response`	`map watch` could not read or parse a status response. Keep the deployment ref and inspect status with `map --json status <deployment-ref>`.
`read <path>`	A read helper received a response from the named route but could not read the response body. Inspect current state before retrying.
`parse <path>`	A read helper received a successful response from the named route but could not parse the JSON body. Keep the raw command output and route path.
`parse publish response`	`map publish` received a successful response but could not parse it. Check `map versions <app>` before retrying publish.
`parse canary response`	`map canary` received a successful response but could not parse it. Check `map versions <app>` before retrying canary changes.
`deployment logs are not available yet`	`map logs` is not the deploy investigation source. Use `map --json status <deployment-ref>` and `map --json evidence <deployment-ref>`.

Error Body¶

Forge control-plane API errors use JSON bodies with these fields:

Field	Meaning
`status`	`error` for an error response.
`code`	Machine-readable error class. Control-plane values include `bad_request`, `forbidden`, `not_found`, `conflict`, and `internal`. Keep the exact value.
`message`	Human-readable detail for the failing input or server-side condition.

Example:

{
  "status": "error",
  "code": "not_found",
  "message": "deployment evidence not found"
}

Read the HTTP status first, then the code, then the message. The CLI redacts token markers before printing the body, but operators must still remove customer credentials, private keys, personal access tokens, GitHub OIDC tokens, and local home paths before sharing the output.

First checks by command area¶

Use the status and body to decide what state to inspect before retrying. Do not retry a command that changes deploy, publish, canary, rollback, onboarding, or access state until you have checked the current state named below.

Command area	What the status usually means	Customer-owned checks before retry
Onboarding	`400` for missing or invalid repo or installation input. `409` when the onboarding request conflicts with recorded state. `5xx` for a control-plane condition the customer cannot fix from the CLI.	Confirm the GitHub owner/repo, installation ref, customer setup context, GitHub App grant, and project/app ref. Re-run onboarding only after one of those inputs or grants changes.
Deploy request	`400` for malformed deploy input. `403` when deploy authority or source authority is not accepted. `409` when a deployment is already in progress, a lease is lost, or recorded state changes during the request. `5xx` when Forge cannot complete the request path. Build, runtime, and route failures are deploy outcomes; inspect deploy status and evidence before treating them as API errors.	Confirm repo, ref or SHA, manifest, app/account refs, GitHub App grant, and saved endpoint context. If a deployment ref exists, inspect `map --json status <deployment-ref>` and `map --json evidence <deployment-ref>` before retrying.
Deploy status	`400` when no deployment ref is available; `404` when the deployment ref is not recorded.	Re-check the deployment ref from the deploy response or `map versions <app>`.
Deploy evidence	`400` when no deployment ref is available; `404` when no evidence object is recorded for that deployment.	Keep `map --json status <deployment-ref>` and the original deploy response; evidence may not exist for every ref.
Access apply	`400` for missing `app_ref` or exposure other than `public` or `protected`. `5xx` when Forge cannot persist the access policy.	Check `access.yaml`, resolved app ref, and `map access plan --repo-dir .` before applying again.
Publish	`400` when the deployment ref is missing, the target has not reached `Succeeded` or `Promoted`, or the target lacks runtime/route materialization fields. `404` when the deployment ref is not recorded. `409` when `--expected-sha` does not match the recorded source SHA or recorded state changes during the publish.	Re-read `map versions <app>`, verify the reviewed Git commit SHA, and publish only the intended `Succeeded` or `Promoted` deployment.
Canary	`400` for missing canary inputs, invalid weight, unknown action, no active canary, or a target that is not materialized. `404` when the named canary deployment, selected alias pointer, current alias target, or deployment ref is not recorded.	Re-read `map versions <app>` and `map --json status <deployment-ref>` before changing traffic.
Rollback	`400` when the deployment ref is missing, unknown to the rollback state transition, or cannot transition to rolled back. `404` when the deployment ref is not recorded after the transition check.	Confirm the deployment ref and current route state before retrying.
Route reads	`404` when the requested control-plane route is not found. `map versions <app>` reads route status and filters pointers for the app; an app with no pointers is not itself a route-read error.	Confirm the CLI endpoint and account context.

Status guide¶

HTTP status	What it means	First customer action
`400 Bad Request`	The request is missing required input, has invalid JSON or flags, points at an invalid ref, or asks for a state transition Forge does not accept.	Re-check the command flags, app ref, deployment ref, Git ref or SHA, and manifest or access-policy input named by `message`.
`403 Forbidden`	The request reached Forge, but the saved token, request authority, or repository/source authority is not accepted for that action.	Run `map whoami`, refresh login if needed, and confirm the repo is granted to the Forge GitHub App when source access is involved.
`404 Not Found`	The route, deployment ref, evidence object, onboarded repo, base deployment, target deployment, or canary deployment is not recorded for this account context.	Confirm the ref came from the same account context. Use `map versions <app>` for app refs and `map --json status <deployment-ref>` before requesting evidence.
`409 Conflict`	The request conflicts with current recorded state, such as a grant conflict, a deployment already in progress, a stale publish guard, or an optimistic-concurrency write conflict.	Re-read current state, re-check the reviewed Git commit SHA when publishing, then retry only after the intended state is still correct.
`500 Internal Server Error`	Forge accepted the request path but could not complete the operation.	Keep the full redacted response body, status, command, and relevant deploy evidence.
Other `5xx`	Forge could not complete the operation.	Do not guess from the status alone. Keep the exact status, body, command, and state reads named above.

What to collect¶

For any control-plane API error, keep:

exact command;
HTTP status;
full response body after redacting customer credentials, bearer strings, private keys, personal access tokens, GitHub OIDC tokens, and local home paths;
map whoami output;
repo owner/name and app ref when the command is repo or app specific;
deployment ref, version label, or canary deployment ref when present;
map versions <app> output when route, publish, clean public URL, or canary state is involved;
map --json status <deployment-ref> output when the deployment ref is known;
map --json evidence <deployment-ref> output when evidence exists.

Use Support and escalation only after the customer-owned checks are complete and the remaining issue is control-plane behavior, source fetch, route state, protected access, publish state, or Mithran-owned route work.

Do not send¶

Do not send raw bearer tokens, GitHub OIDC tokens, personal access tokens, private keys, passwords, customer credentials, or unredacted local machine paths. Repo Variables used by the optional custom-CI workflow are acceptable when they are non-secret values such as refs and endpoint names.