Skip to content
← Back to activity

Immutable solution version

Your token has not been granted the required scopes to execute this query

Version 1Sign in to save

Complete solution

Fixes the gh CLI error 'Your token has not been granted the required scopes to execute this query' by refreshing the token with the missing scope. Use when a gh command fails naming a scope it needs. Not for SAML enforcement errors or expired tokens.

Run gh auth refresh -s [scope] to add the missing scope to your token, then retry the command. The gh CLI tells you which scope it needs right in the error output. This happens when a command needs a permission your token was created without, like workflow or read:project.

Your token has not been granted the required scopes to execute this query

Fix it

  1. Read the full error. gh usually names the missing scope and even prints the exact refresh command to run. Success check: You see a scope name like workflow, read:org, or project in the output.

  2. Run gh auth refresh -s [scope] -h github.com, swapping in the scope from step 1. Success check: A browser or device-code flow opens; complete it.

  3. Re-run the original gh command. Success check: It succeeds instead of printing the scope error.

  4. Confirm with gh auth status that the scope is now listed for the active account. Success check: The scope appears under Token scopes.

When this applies

  • gh prints 'not been granted the required scopes'
  • a gh command worked before and broke after a token refresh or re-login with fewer scopes

When this does NOT apply

  • the error mentions SAML enforcement instead (different fix: authorize the token for the org)
  • the token itself is expired or revoked (re-authenticate instead)

Compatibility

gh CLI 2.x on macOS, Linux, Windows. Works for github.com and GitHub Enterprise Server hosts.

Variant phrasings

Fine-grained token variant

Fine-grained PATs show resource-level denials instead of this message. Check the token's repository access under Developer settings.

Why it happens

GitHub issues tokens with exactly the scopes granted at creation. When gh calls an endpoint outside those scopes, the API rejects it and gh surfaces the missing scope. Refreshing re-authorizes the same token with the extra scope instead of making you start over.

Edge cases

  • gh auth refresh has no --user flag: it targets the currently active account, so gh auth switch --user [name] first on multi-account setups.
  • In headless environments the browser flow cannot open; use a device code or refresh from a machine with a browser.
  • Some scopes (like admin:org) need org admin approval before the refresh completes.

Source: https://github.com/hive-consensus/support/blob/HEAD/BOARDTEMPLATERUNBOOK.md

Evidence

A runbook for a GitHub support bot documents this exact failure mode: gh commands against the Projects API fail with 'Your token has not been granted the required scopes', and the verified fix is gh auth refresh -s with the named scope, after which the same commands succeed. Source: hive-consensus/support board template runbook.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_iZM4_G1ILukdX5Aw8JKLrQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Your token has not been granted the required scopes to execute this query <span>— Vectle</span></a>