Skip to content

Errors

Every failure a Diatreme run can surface, what causes it, and what to do. The action fails hard: any broker fault exits the step non-zero, so a broken broker is a red X on the release rather than a silent skip.

Reading a broker failure in the run log

The action prints the HTTP status, the error code, the reason when there is one, and which broker answered:

Error: Token broker request failed with HTTP 401: invalid_oidc_token (audience_mismatch) [https://api.diatreme.magmamoose.com]

The hostname in brackets matters. If it's the fallback rather than the primary, the primary was unreachable or returned 5xx and you have two problems, not one. A preceding ::warning:: line names the primary's status.

Token verification failures

All of these are 401 invalid_oidc_token unless noted. The reason is what tells you which check failed.

reason What it means What to do
malformed_token The value sent as oidcToken isn't a decodable JWT. Almost always a broken OIDC mint upstream of the broker. Check the Request public GitHub App token step actually received a token, and that id-token: write is granted.
audience_mismatch The token's aud isn't in the broker's accepted list. Your oidc-audience input and the broker's OIDC_AUDIENCE disagree. Leave the input at its default unless you run your own broker.
issuer_mismatch The token's iss isn't a trusted issuer. Expected on a GitHub Enterprise runner talking to a broker without GHE_OIDC_ISSUER configured. See Configuration.
token_expired exp is in the past. The token is minted seconds before use, so this means real clock skew or a job that stalled for an hour between mint and exchange. Re-run.
token_not_yet_valid nbf is in the future. Clock skew on the broker side. Re-run, and if it persists, report it.
signature_invalid The signature didn't verify against a key that matched. Not something a caller can cause with a genuine token. Report it.
kid_not_found No signing key matched the token's kid, even after a forced re-fetch. Usually a GitHub key rotation the broker hasn't caught up with. Retry once. If it persists past a few minutes, report it.
key_ambiguous More than one key matched the kid. Report it. Not caller-fixable.
alg_unsupported The token's algorithm isn't allowed. Report it.
claim_invalid A claim other than aud, iss or nbf failed validation. Report it with the run URL.
unknown The failure carried no classifiable code. Report it with the run URL.

403 repo_mismatch

The token's repository claim isn't the owner/repo the request asked for. The broker will not mint a token for a repository other than the one whose runner minted the OIDC token, which is the property that makes a public broker safe. Seeing this from an unmodified action means something rewrote the request.

403 repo_not_allowed

The repository is outside the broker's ALLOWED_REPOSITORIES. On a self-hosted broker, add it. On the hosted broker this shouldn't happen; report it.

404 app_not_installed

The Diatreme GitHub App isn't installed on the repository. Install it from github.com/apps/diatreme and re-run. This is the single most common first-run failure.

400 invalid_repository

owner or repo contains a character outside A-Za-z0-9_.-. Not reachable through the action, which derives both from GITHUB_REPOSITORY.

Availability failures

503 oidc_key_fetch_failed with reason: jwks_unavailable

The broker could not retrieve the issuer's key set, so it never reached a verdict on your token. This is broker or upstream unavailability, not a bad token, and it is worth retrying.

Causes seen in practice: a timeout or connection reset reaching token.actions.githubusercontent.com, a non-200 from that endpoint, or a response that doesn't parse as JSON.

What to do: re-run the job. The broker keeps a last-known-good key set and will rescue the request from it when one is available and fresh enough, so a persistent 503 means both the live fetch and the snapshot are unusable.

Why this isn't a 401

It used to be. A bare catch turned every retrieval fault into invalid_oidc_token, which sent people hunting for a bad token during what was actually an outage, with no way to tell the two apart (#147). Retrieval faults are 503 now, and only 503.

500 github_installation_lookup_failed

GitHub answered the installation lookup with something the broker couldn't use. Transient. Re-run, and check GitHub's status page if it repeats.

502 installation_token_failed / 502 sign_failed

Only on /sign. The first means no token could be minted for that repository, the second that GitHub rejected the commit. The usual cause of sign_failed is a stale expected_head_oid: the branch moved between reading the head and writing the commit. Re-read the head and retry.

503 sign_disabled / 503 releases_disabled / 503 webhook_disabled

The relevant secret isn't configured on that deployment. See Configuration. On a self-hosted broker this is your answer. On the hosted one, report it.

Client-side action failures

These come from the action's own scripts, before or instead of a broker call.

Message Cause Fix
auth-mode public-app requires token-broker-url. token-broker-url was explicitly set to an empty string. Leave it unset to get the default, or give it a real URL.
OIDC request environment is unavailable. Grant 'id-token: write' to this job. The job has no OIDC permission, so no token can be minted at all. Add permissions: id-token: write to the job. See Setup.
GITHUB_REPOSITORY must be owner/repo. The environment variable is missing or malformed. Only reachable outside a normal Actions run.
Token broker request failed with HTTP <status>: <error> The broker answered non-200. Find the error and reason in the tables above.
deploy-paths must be a JSON array of directories deploy-paths is not a JSON array of relative directories. Checked before anything is tagged. Fix the value, e.g. ["k8s/overlays/acc", "k8s/overlays/prd"].
This push changes nothing but deploy-paths A deploy PR merged into a branch whose push trigger does not ignore those directories. Nothing was tagged. Add them to the push trigger's paths-ignore.

promote-from refusals

Every message in this table starts with promote-from:. All but the last stop the run before a tag, an image or a GitHub Release is written.

Message Cause Fix
tag '<tag>' does not exist in this repository The tag was mistyped, or never cut. The message lists the prereleases of that version that do exist. Promote one of those.
'<tag>' is already a stable version A stable tag was passed. Pass the prerelease, e.g. v1.5.0-rc.3.
'<tag>' is not a prerelease tag under tag-prefix '<prefix>' The value is not a SemVer prerelease in this package's tag series. Check tag-prefix matches the one the prerelease was cut with.
is a '<id>' prerelease, but only '<id>' prereleases are promoted to stable The tag is from a channel other than the one that feeds production: the environment before the last in environments. Promote that channel's build, or correct environments and prerelease-identifiers.
<tag> already exists on commit <sha> A different build was already released as that stable version. Cut a new version. If the tag was a mistake, delete it and its GitHub Release first.
<tag> was already promoted from <other> Another prerelease on the same commit was already promoted to that version. It is a separate image, so promoting this one would repoint a published version. Cut a new version.
was not cut by a promotion The stable version already exists on this commit and its tag has no Promoted-From line: an ordinary release cut it. Nothing to promote; it is released.
cannot be combined with version-override / force-bump The version of a promotion is the source tag's own. Remove the other input.
cannot be combined with publish-package and package-ecosystem: container That path runs docker build and would push a fresh image under the stable version. Promote the image through a bake file or Dockerfile, or turn publish-package off for the run.
npm-provenance would attest the package to commit <sha> The workflow was started on a commit other than the prerelease's, and npm attests to the workflow's commit. Start the workflow from the prerelease tag, or turn npm-provenance off for the run.
a promotion always releases the stable version, to '<env>' environment names something other than the last entry of environments. Remove environment.
environments is not a JSON array / prerelease-identifiers is not a JSON object One of the two inputs does not parse. Fix the JSON.
source image(s) are not in the registry The prerelease has a git tag but no image: its build failed, or a retention policy removed it. Cut a new prerelease and promote that one.
could not retag <source> as <target> The registry refused the retag after the stable tag was pushed. The message carries the registry's error. Fix the cause and re-run. The promotion resumes from the tag that is already there; it never falls back to a rebuild.

Two more come from the tag push itself, without the prefix, when the remote already holds the stable tag and it is not this promotion's:

Message Cause Fix
Tag <tag> already exists on remote at <sha>, not at <sha> Another run released a different build as that version between this run's checks and its push. Cut a new version.
Tag <tag> already exists on remote on the commit being released, but it is not this release The tag on the remote does not record this prerelease as its source. Cut a new version.

See Promoting a release candidate to stable.

cut-release-branch refusals

Every message in this table starts with cut-release-branch:, and none of them leaves a branch behind.

Message Cause Fix
version-override is required The mode was run without a version. Pass the version to cut, e.g. 1.4.0.
'<v>' carries a prerelease part A release branch is named after the release number only. Pass X.Y.Z. The candidates cut from the branch get their -rc.N themselves.
'<v>' is not a version The value is not major.minor.patch. Fix the value.
<tag> is already released That version shipped. Pick the next version, or run on that line's latest tag to reopen it for a patch.
<v> is not above <tag>, the newest release A new release branch takes a higher version than anything released. Pick a higher version, or reopen the older line from its latest tag.
release/<v> already exists on <sha> A release branch is cut once. Ship fixes to it through hotfix pull requests, or delete it first to start over.
could not create release/<v> The token cannot create the branch: no contents: write, or a ruleset restricting release/* creation that the App cannot bypass. Grant it, or add the App to the ruleset's bypass list.
could not check whether release/<v> exists The branch lookup failed with something other than "not found". Usually transient or a token problem; the message carries the API error.

release-branch-merge-back and release-branch-cleanup never fail a release: everything that goes wrong after the release is out (a merge-back branch that cannot absorb a conflict, a branch a ruleset protects from deletion) is a warning naming the manual step. See Releasing from release branches.

Getting more detail

On the Cloudflare deployment, every verification failure logs one structured line:

npx wrangler tail diatreme --format json --search oidc_verify_failed

It carries the classified reason, the underlying error name and code, the token's kid, iss, aud, repository, iat and exp, the audiences and issuers the broker expected, and for a retrieval fault the upstream HTTP status and content type. It never carries the token itself. Field values are truncated, so a hostile token can't flood the log.