Troubleshooting

Every message on this page is copied from the source. FORGE passes GitHub’s and the inference plane’s own error text through unparaphrased, so a … below stands for their words.

Access

Message	Meaning	Fix
`FORGE is opened from CORE — sign in to CORE`	The request carried no valid `X-Core-Identity`: it was missing, expired, badly signed, meant for the wrong audience, or duplicated	Open FORGE from CORE’s rail. Locally, go through `forge dev proxy` rather than the backend’s own port.
`CORE did not vouch for you — sign in to CORE again.`	The studio got `Unauthenticated` mid-session, because CORE’s session ended	Sign in to CORE again
`this account is not on this forge instance's allowlist (FORGE_OWNER_EMAIL)`	CORE vouched for you, but `FORGE_OWNER_EMAIL` is set and does not list you	Add the address, or unset the allowlist
`forge cannot verify CORE's identity assertions: CORE_FORGE_IDENTITY_KEY is unset or invalid (base64 of at least 32 random bytes, shared with CORE's console)`	A deployment fault, answered on every RPC	Provide the key, the same value CORE’s console uses
The studio’s assets fail to load at the backend’s `/`	The bundle is built for `/forge/`	Browse through CORE, or through `forge dev proxy` at `/forge/`

Configuration

Message	Meaning	Fix
`the forge is not connected to GitHub yet — CORE_GH_APP_ID / CORE_GH_APP_PRIVATE_KEY are unset on this deployment`	No GitHub credentials	Set the App credentials. Locally, set `FORGE_GITHUB_TOKEN`.
`FORGE's encrypted store (appfs) is not mounted, so chats cannot be kept — see the server log for why (usually CORE_ENVELOPE_KEK)`	appfs did not mount	Read the startup line `appfs not mounted: …`. Usually `CORE_ENVELOPE_KEK` is missing, or an object store is set but broken.
`the forge audit log (appfs var/log/forge) is not mounted, and the forge does not act unattributed`	The same root cause, met on an approval	As above
`OBJECTSTORE_ENDPOINT is set but the object store did not open: …`	objectd is configured but unreachable. FORGE will not fall back to local disk.	Fix the endpoint or keys, or unset them to use `FORGE_APPFS_DIR`
`the planner is not connected to the platform's own model — INFERENCE_URL / INFERENCE_MODEL unset on this deployment`	The planner has no model. Typed commands still work.	Set both. `INFERENCE_MODEL` has no default.

GitHub

Message	Meaning	Fix
`GitHub refused the repository: …`	Creating the repo failed. GitHub’s reason follows.	Read GitHub’s words. The App may lack repository-creation permission in the organisation.
`… Resource not accessible by integration`	The App lacks a permission for that call	Grant the permission to the platform App
`the App has no installation on <org>`	The App is not installed on `FORGE_GITHUB_ORG`	Install it, or fix the organisation
`repo created but not tagged: …` / `repo created and tagged but not seeded: …`	A partial create. Topics are written before the seed, so the repo can still be listed.	Read the cause. The repo exists, so don’t re-create it under the same name.
`<lane>: the work order failed to file: …`	The repo or manifest step worked, but one lane’s issue did not	Send that lane’s brief again
`forge.yaml could not be written: …`	The structure change did not commit	Retry the approval
`the repo's forge.yaml is invalid, so FORGE will not overwrite it blind: …`	Someone edited `forge.yaml` by hand and broke it	Fix the file on GitHub so it parses, then approve again. See the spec.
`GitHub is not answering: …`, `could not read forge.yaml: …`, `GitHub: …`	GitHub could not be read	Try again. Failures are never cached.
A chat shows lanes but no status, with a reason	`status_error`: GitHub could not be read for that chat. The status is left absent, never guessed.	Try again or Re-read from GitHub

Chats and approvals

Message	Meaning
`name the project first (the project needs a short machine name: lowercase letters, digits, hyphens — it becomes the repo)`	The first approval needs a project name. Type `project <name>`.
`Name the project first — it becomes the repo: project <name>`	The same rule, from the studio before it sends
`add a lane first — a project is its lanes`	An approval with no lanes
`the first approval needs at least one lane brief — it is what the coding agent builds`	A first approval with only structure
`lane "…": describe the change in at least a sentence — it is handed to the coding agent verbatim`	The brief is shorter than 12 characters
`lane "…": brief too long (8000 chars max)`	The brief is too long
`no lane "…" in this project` / `one brief per lane: "…" has two`	The briefs do not match the lanes
`the project's repo exists; its name no longer changes`	Renaming after the first approval
`lane "…": setting "…" looks like a credential — credentials are set in CORE › Connections, never here`	A secret-looking setting key
`could not record this request in the forge audit log, so it was not sent: …`	The audit append failed, so nothing reached GitHub
`no such chat` / `not a chat id`	An unknown chat, or an id that is not `c-<16 hex>` or `repo-<name>`
`chats: at most 500 chats per person`	The per-person limit

Lane-structure errors (at most 12 lanes per project, folder "…" is inside folder "…", and so on) are listed under Projects and lanes.

Planner

Message	Meaning
`the planner is still thinking about the previous message — the platform's own model decodes one plan at a time on CPU; wait for that plan, then ask again`	`ResourceExhausted`: a plan is already decoding. It is not queued.
`the planner forgot this plan (restart or expiry) — ask again`	`NotFound`: the server restarted, or the plan finished more than an hour ago
`the model did not answer with a JSON plan: …` / `the model's plan is not valid JSON (…): …`	The model’s output could not be parsed as a plan
`inference <code>: …`	The inference plane answered with an HTTP error. Its text follows.
`N proposed step(s) failed validation and were dropped.`	Some steps broke the rules and were dropped, not repaired
A step marked judge dissents	The judging gate disagreed. The step is offered only as Use anyway.

Verification

What you see	Meaning
No verification yet	No `core/ci` has been posted on the default-branch HEAD. CORE’s sweep has not reached the repo, or it is not posting.
Nothing built yet	`failure` with `Nothing to verify yet: …`. No code has landed in that lane folder. This is not a broken build.
`forge.yaml is invalid: …` on `core/ci`, and no lane statuses	CORE could not read the manifest
Verification failed with Open the CORE run	A real failure. The run link is `target_url`.
The coding agent stage stays WAITING	No work order has been closed. No forged PR has landed yet anywhere, and the coding agent opens only draft PRs.

Sources

grpc/cmd/{auth_interceptor,chat_server,forge_server,plan_server,iterations_server}.go; grpc/internal/{auth,appstate,chats,ghforge,planner,project}/; flutter/lib/core/auth/core_gate_screen.dart; flutter/lib/core/grpc/channel_provider.dart; flutter/lib/features/forge/project/project_loop.dart.

Status