SAM Doctor

ERROR REFERENCE

Unable to get ID Token (missing id-token: write)

The job tried to request a GitHub OIDC token and the runner refused before AWS was ever involved. The workflow (or the job) lacks the id-token: write permission the credentials step needs.

WHAT IT MEANS

What this error means

OIDC-based AWS auth starts with the job minting a short-lived identity token from GitHub. That minting is gated by the permissions: block — and setting any permission explicitly drops all the unlisted ones, which is how adding an innocent contents: read silently removes id-token: write from a previously working job.

FIX

How to fix it

  1. Grant it where the credentials step runs: 
    permissions:
  id-token: write
  contents: read
    At the workflow level or on the specific job - the job-level block overrides the workflow's.
  2. For reusable workflows, the caller must pass the permission too; a called workflow cannot grant itself more than the caller gave it.
  3. Check the fork case. Pull requests from forks run with restricted permissions by design; OIDC deploys belong on push/workflow_dispatch events, not fork PRs.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the token-request refusal (high confidence) and keeps it distinct from AWS-side OIDC rejections, which have their own rules and pages. Runs locally; no AWS access, no log upload. 

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED