{"record":{"id":"f2b46165dec395b5","repo":"mislav/hub","slug":"your-access-token-may-have-insufficient-scopes-vi","errorCode":null,"errorMessage":"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","messagePattern":"Your access token may have insufficient scopes\\. Visit (.+?)://(.+?)/settings/tokens\\\\nto edit the 'hub' token and enable one of the following scopes: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"github/client.go","lineNumber":1301,"sourceCode":"\n// ValidateSufficientOAuthScopes warns about insufficient OAuth scopes\nfunc ValidateSufficientOAuthScopes(res *http.Response) error {\n\tif res.StatusCode != 404 && res.StatusCode != 403 {\n\t\treturn nil\n\t}\n\n\tneedScopes := newScopeSet(res.Header.Get(\"X-Accepted-Oauth-Scopes\"))\n\tif len(needScopes) == 0 && isGistWrite(res.Request) {\n\t\t// compensate for a GitHub bug: gist APIs omit proper `X-Accepted-Oauth-Scopes` in responses\n\t\tneedScopes = newScopeSet(\"gist\")\n\t}\n\n\thaveScopes := newScopeSet(res.Header.Get(\"X-Oauth-Scopes\"))\n\tif len(needScopes) == 0 || needScopes.Intersects(haveScopes) {\n\t\treturn nil\n\t}\n\n\treturn fmt.Errorf(\"Your access token may have insufficient scopes. Visit %s://%s/settings/tokens\\n\"+\n\t\t\"to edit the 'hub' token and enable one of the following scopes: %s\",\n\t\tres.Request.URL.Scheme,\n\t\treverseNormalizeHost(res.Request.Host),\n\t\tneedScopes)\n}\n\nfunc isGistWrite(req *http.Request) bool {\n\tif req.Method == \"GET\" {\n\t\treturn false\n\t}\n\tpath := strings.TrimPrefix(req.URL.Path, \"/v3\")\n\treturn strings.HasPrefix(path, \"/gists\")\n}\n\ntype scopeSet map[string]struct{}\n\nfunc (s scopeSet) String() string {\n\tscopes := make([]string, 0, len(s))","sourceCodeStart":1283,"sourceCodeEnd":1319,"githubUrl":"https://github.com/mislav/hub/blob/5c547ed804368763064e51f3990851e267e88edd/github/client.go#L1283-L1319","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before: token created without 'gist' scope\n// after: create token with scopes repo, gist, read:org, then:\n// export GITHUB_TOKEN=ghp_newTokenWithScopes","handlingStrategy":"validation","validationCode":"// Check token scopes before making API calls where possible:\n// inspect the response header yourself once, early:\nresp, _ := http.Get(baseURL + \"/user\")\nscopes := resp.Header.Get(\"X-OAuth-Scopes\")\nif !strings.Contains(scopes, \"repo\") {\n    log.Fatal(\"token lacks required 'repo' scope; regenerate at /settings/tokens\")\n}","typeGuard":null,"tryCatchPattern":"// Go: hub uses utils.Check internally; callers can wrap:\nif err := client.API(...); err != nil {\n    if strings.Contains(err.Error(), \"insufficient scopes\") {\n        fmt.Fprintf(os.Stderr, \"Fix your token at %s://%s/settings/tokens\\n\", scheme, host)\n        os.Exit(1)\n    }\n    return err\n}","preventionTips":["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"],"tags":["oauth","scopes","authentication","github"],"backgroundTag":"oauth-insufficient-scope","analyzedSha":"5c547ed804368763064e51f3990851e267e88edd","analyzedAt":"2026-09-01T03:34:15.525Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}