Troubleshooting
Every message below is quoted from CORE’s code: forgeproxy.go, forge.go, grpc/cmd/forgecheck, core-verify.yml, core-verify-sweep.yml and core-forge-run.yml.
The Studio frame shows “FORGE is not available here”
This is the /forge/ proxy refusing the request. The page shows the message and the status, followed by “served by CORE’s /forge/ proxy”. A non-browser caller gets the same message as {"error": "…"}.
| Status | Message | Cause | Fix |
|---|---|---|---|
| 401 | sign in to CORE to use FORGE | No CORE session on the request, including on a console running with sign-in disabled | Sign in to the console. FORGE has no sign-in of its own |
| 503 | FORGE is not wired: CORE_FORGE_IDENTITY_KEY is not configured (core-system Secret forge-identity-key, minted by core-operator) | The console cannot resolve the identity key | Check that core-operator’s provisioner minted core-system/forge-identity-key and that the console pod projects it |
| 503 | FORGE is not wired: CORE_FORGE_IDENTITY_KEY is not base64 (…) | The key value is not base64 | Re-mint the Secret through the provisioner. Do not hand-edit it |
| 503 | FORGE is not wired: CORE_FORGE_IDENTITY_KEY decodes to N bytes; at least 32 are required (…) | The key is too short | As above |
| 503 | FORGE is not wired: FORGE_UPSTREAM="…" is not an http(s) URL | FORGE_UPSTREAM is set to something unusable | Unset it (the default is the in-cluster Service) or set it to a full http(s)://host[:port] |
| 500 | could not sign the FORGE identity assertion | Signing failed | Check the console log. The key is present but unusable |
| 502 | FORGE is unreachable | The upstream did not answer. The console logs forge proxy: upstream unreachable with the upstream URL | Check that the forge Deployment in forge-system is running and that the NetworkPolicy admits the core-operator pod on 8080 |
The rail shows FORGE as unreadable
The chat history comes from FORGE through the same proxy. An unreadable list shows the reason and a retry, and the reason is usually one of the proxy errors above. Outside a browser, the channel cannot be built at all (“FORGE (behind the console’s /forge/ proxy)” is only reachable from the web console).
GET /api/forge errors
| Status | Message |
|---|---|
| 405 | CORE no longer files briefs — open FORGE › Studio and send it there. A client still POSTing a brief. Briefs are filed in FORGE |
| 503 | the forge needs the CORE GitHub App configured (CORE_GH_APP_*) |
| 503 | the forge could not reach its GitHub App installation: <reason> |
| 503 | the CORE GitHub App installation names no account, so the forge does not know which org to list forged apps from. The App has to be reinstalled on the org |
| 502 | github <status> on <METHOD> <path>: <body> |
In unmeasured[] (the list still answers 200):
state is read for the 12 most recently updated apps per request; not read for …the GitHub quota is at or below the N calls kept for the agent fleet, so the state of … was not readGitHub's repository listing named no default_branch for <org>/<repo>, so its core/ci verification cannot be scoped to it
core/ci descriptions
“Nothing to verify yet…”
| Description | Cause | Fix |
|---|---|---|
Nothing to verify yet: no .dsl or .herd file and no Go package | A pipeline repository with no pipeline files and no Go package | Write the pipeline. This is a deliberate failure, not a skip |
Nothing to verify yet: <path> does not exist (per lane) | The lane is declared in forge.yaml but its folder is not written yet | Expected for a new lane |
Nothing to verify yet: no .dsl or .herd file and no Go package in <path> | An empty pipeline lane | Add .dsl/.herd files or Go code |
Nothing to verify yet: no go.mod or package.json in <path> | An empty web lane | Add a go.mod or a package.json (in the folder or its web/) |
Nothing to verify yet: no component has code yet (aggregate) | Every lane is empty | As above |
forge.yaml is invalid
core/ci = failure, with no per-lane status. The description is forge.yaml is invalid: <first reason>. Reasons are quoted from manifest.go:
the file is empty·not valid YAML: …·more than one YAML documentno version (want version: 1)·version … is not supported (want 1)no lanes·N lanes, more than the 50 CORE verifieslane N: id "…" must match ^[a-z0-9][a-z0-9-]{0,38}$·lane N: id "…" repeats lane Mlane <id>: kind "…" is not pipeline or web·lane <id>: name is longer than 80 characterslane <id>: path "…" is empty | is absolute | has a trailing / | contains a backslash or NUL | contains a control character | leaves the repository (..) | is not clean (no ./, // or trailing .)lane <id>: path "." is allowed only when there is exactly one lane·lane <id>: path "…" repeats lane M·lane <id>: path "…" is inside lane <id> ("…")forge.yaml is a symlink; it must be a regular file·forge.yaml is not a regular file·forge.yaml is larger than 1 MiB
Check a manifest locally with go run ./cmd/forgecheck manifest -file <path> from CORE’s grpc/.
Failures (the checks ran and said no)
| Description | Where |
|---|---|
N of M pipeline file(s) not valid TOML, first: <file> | pipeline profile or lane |
go vet / build / test -race failed in grpc/ · flutter pub get failed · flutter analyze failed · flutter test failed · flutter build web failed | forge profile |
go build / vet / test failed (or no go.mod at the root) · npm ci failed in web/ (or no web/package.json) · npm run build / lint failed in web/ | web profile |
go build / vet / test failed · pipeline files failed the TOML check | pipeline profile |
go <build|vet|test> failed in <path> · npm <step> failed in <path> · <path>/package.json is not valid JSON · <path> is not a folder · <path> points outside the repository | a forge.yaml lane |
N/M components failed — <id>: <why> | the aggregate |
Open the target_url (the core-verify.yml run) for the log. The run’s step summary has a per-component table.
Errors (the checks could not run)
| Description | Cause |
|---|---|
CORE refused or could not read the target (public, not forged, or unreadable) — see the run | The target is public, is neither forge nor tagged forged, or could not be read |
could not check out the commit | Checkout failed |
Go 1.26 is not in the runner toolcache | Runner image problem |
no baked Flutter SDK on the runner (/opt/flutter) | Runner image problem. The workflow deliberately does not download it |
no Node/npm on the runner — the frontend could not be verified (or … the web components could not be verified) | No Node on PATH and none at $HOME/externals/node24/bin |
could not check out org-runink/security (a sibling FORGE builds against) · could not check out org-runink/store … · could not check out CORE's forgecheck · could not build forgecheck | Token scope or checkout failure |
forgecheck could not read forge.yaml · forgecheck could not read the checkout | forgecheck exited 2 |
verification did not complete (<step>: <outcome>) — cancelled or timed out | Cancelled or timed-out run (45-minute job timeout) |
verification did not complete — cancelled or timed out (per lane) | The lane never recorded a result |
N/M components could not be verified — <id>: <why> | The aggregate over lane errors |
could not aggregate the component results (agg: <outcome>) | The aggregate step did not succeed |
core/ci stays at “queued for CORE verification”
The sweep claimed the commit and dispatched it, but no run picked it up, or the run died. Nothing to do: a pending status older than 90 minutes is re-dispatched by the next sweep. If the sweep itself fails with N dispatch(es) to org-runink/core failed — see the warnings, the dispatch call failed, and the stale rule retries it.
Commits that are never dispatched: anything in a public repository, fork PRs, archived or disabled repositories, and a repository with no default-branch head yet (an empty repo).
A brief sits in the queue and nothing builds it
The forger (core-forge-run.yml) is disarmed by default. Its step summary says “Forger is DISARMED” and names who decided (env, console or default). Arm it with the Actions variable CORE_FORGE_ENABLED=true or the console’s agent control. Outcomes on the issue:
forge:doneand “Forger opened a draft PR: …”forge:failedand “Forger produced nothing for this brief — …”, where the reason is one of: the session never started (the sibling clone or thecoreCLI build failed before it), the session finished but produced no pull request (no changes, or it ran out of turns), or the session exited N. A failed issue is not retried. Re-add theforgelabel to requeue it.