Your access token may have insufficient scopes. Visit %s://%

Error message

Your access token may have insufficient scopes. Visit %s://%s/settings/tokens\nto edit the 'hub' token and enable one of the following scopes: %s

What it means

After an API response, the client compares the scopes granted to the OAuth token (from the X-OAuth-Scopes response header) against the scopes the operation requires. If the token exists but shares none of the required scopes, this error is returned telling the user to edit the 'hub' token on GitHub. It is a proactive configuration check, not a response from the GitHub API itself.

Source

Thrown at github/client.go:1301

// ValidateSufficientOAuthScopes warns about insufficient OAuth scopes
func ValidateSufficientOAuthScopes(res *http.Response) error {
	if res.StatusCode != 404 && res.StatusCode != 403 {
		return nil
	}

	needScopes := newScopeSet(res.Header.Get("X-Accepted-Oauth-Scopes"))
	if len(needScopes) == 0 && isGistWrite(res.Request) {
		// compensate for a GitHub bug: gist APIs omit proper `X-Accepted-Oauth-Scopes` in responses
		needScopes = newScopeSet("gist")
	}

	haveScopes := newScopeSet(res.Header.Get("X-Oauth-Scopes"))
	if len(needScopes) == 0 || needScopes.Intersects(haveScopes) {
		return nil
	}

	return fmt.Errorf("Your access token may have insufficient scopes. Visit %s://%s/settings/tokens\n"+
		"to edit the 'hub' token and enable one of the following scopes: %s",
		res.Request.URL.Scheme,
		reverseNormalizeHost(res.Request.Host),
		needScopes)
}

func isGistWrite(req *http.Request) bool {
	if req.Method == "GET" {
		return false
	}
	path := strings.TrimPrefix(req.URL.Path, "/v3")
	return strings.HasPrefix(path, "/gists")
}

type scopeSet map[string]struct{}

func (s scopeSet) String() string {
	scopes := make([]string, 0, len(s))

View on GitHub (pinned to 5c547ed804)

Solutions

Open the token settings page printed in the error (https://github.com/settings/tokens or your GHE equivalent) and enable at least one of the listed scopes on the 'hub' token.
Regenerate the token with the required scopes and update it via `hub config` or the GITHUB_TOKEN/HUB_TOKEN environment variable.
Re-run `hub` interactively so PromptForHost can create a fresh token with the correct scopes.
Verify the host entry in ~/.config/hub points at the intended host so the right token is used.

Example fix

// before: token created without 'gist' scope
// after: create token with scopes repo, gist, read:org, then:
// export GITHUB_TOKEN=ghp_newTokenWithScopes

Defensive patterns

Strategy: validation

Validate before calling

// Check token scopes before making API calls where possible:
// inspect the response header yourself once, early:
resp, _ := http.Get(baseURL + "/user")
scopes := resp.Header.Get("X-OAuth-Scopes")
if !strings.Contains(scopes, "repo") {
    log.Fatal("token lacks required 'repo' scope; regenerate at /settings/tokens")
}

Try / catch

// Go: hub uses utils.Check internally; callers can wrap:
if err := client.API(...); err != nil {
    if strings.Contains(err.Error(), "insufficient scopes") {
        fmt.Fprintf(os.Stderr, "Fix your token at %s://%s/settings/tokens\n", scheme, host)
        os.Exit(1)
    }
    return err
}

Prevention

Create tokens with all scopes hub documents (repo, gist, read:org) up front
Re-check scopes after editing any token on github.com/settings/tokens
Prefer interactive `hub` login so it requests the correct scopes automatically

When it happens

Trigger: Any authenticated GitHub API call whose response reports an X-OAuth-Scopes header that does not intersect with the scopes required by the operation (needScopes is non-empty and Intersects(haveScopes) is false).

Common situations: Users created a personal access token with only default scopes (e.g. just 'repo' when 'gist' or 'read:org' is needed), or revoked/edited token scopes after hub originally created it; GitHub Enterprise hosts with tokens minted for other services.

Related errors

AI-assisted analysis of mislav/hub@5c547ed804 (2026-09-01). Data as JSON: /api/errors/f2b46165dec395b5. Report an issue: GitHub.