{"record":{"id":"477d3db59544934a","repo":"netbirdio/netbird","slug":"access-token-response-returned-code-s","errorCode":null,"errorMessage":"access token response returned code: %s","messagePattern":"access token response returned code: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/internal/auth/device_flow.go","lineNumber":237,"sourceCode":"\tres, err := d.HTTPClient.Do(req)\n\tif err != nil {\n\t\treturn TokenRequestResponse{}, fmt.Errorf(\"failed to request access token with error: %v\", err)\n\t}\n\n\tdefer func() {\n\t\terr := res.Body.Close()\n\t\tif err != nil {\n\t\t\treturn\n\t\t}\n\t}()\n\n\tbody, err := io.ReadAll(res.Body)\n\tif err != nil {\n\t\treturn TokenRequestResponse{}, fmt.Errorf(\"failed reading access token response body with error: %v\", err)\n\t}\n\n\tif res.StatusCode > 499 {\n\t\treturn TokenRequestResponse{}, fmt.Errorf(\"access token response returned code: %s\", string(body))\n\t}\n\n\ttokenResponse := TokenRequestResponse{}\n\terr = json.Unmarshal(body, &tokenResponse)\n\tif err != nil {\n\t\treturn TokenRequestResponse{}, fmt.Errorf(\"parsing token response failed with error: %v\", err)\n\t}\n\n\treturn tokenResponse, nil\n}\n\n// WaitToken waits user's login and authorize the app. Once the user's authorize\n// it retrieves the access token from Hosted's endpoint and validates it before returning.\n// The method creates a timeout context internally based on info.ExpiresIn.\nfunc (d *DeviceAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowInfo) (TokenInfo, error) {\n\t// Create timeout context based on flow expiration\n\ttimeout := time.Duration(info.ExpiresIn) * time.Second\n\twaitCtx, cancel := context.WithTimeout(ctx, timeout)","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/internal/auth/device_flow.go#L219-L255","documentation":"Raised by DeviceAuthorizationFlow.requestToken when the IdP token endpoint answers with a status code above 499 (device_flow.go:236-238). The raw response body is embedded in the error text, so the message typically contains the IdP's HTML or JSON error payload. It signals a server-side failure (or a middlebox answering 5xx) during the device-flow token poll, as opposed to a protocol-level OAuth error, which arrives as 200/4xx with an error JSON body.","triggerScenarios":"The token POST (client_id + device_code + grant_type) returns 500/502/503/504. Typical producers: IdP outage or maintenance, IdP gateway rate-limiting the polling, a reverse proxy in front of the IdP returning 502/504, or an auth service bug. Note this fires during WaitToken polling, so it can appear after the user already opened the verification URI.","commonSituations":"Auth0/Keycloak/Zitadel incidents or deploys, misconfigured reverse proxy (nginx/traefik) in front of the IdP timing out upstream, user polling during IdP maintenance windows.","solutions":["Read the embedded body in the error message - it usually names the failing upstream component","Retry netbird up after a short wait; 5xx bursts during IdP deploys are usually transient","Check the IdP status page and the reverse-proxy logs in front of the token endpoint","If persistent, verify the TokenEndpoint configured on the management side points to the correct, healthy IdP URL"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"token, err := flow.WaitToken(ctx, info)\nif err != nil && strings.Contains(err.Error(), \"access token response returned code:\") {\n\t// IdP/middlebox 5xx: wait and restart the flow rather than reporting a config problem\n\tlog.Warnf(\"IdP 5xx during token poll: %v\", err)\n\ttime.Sleep(30 * time.Second)\n\treturn retryLogin(ctx)\n}","preventionTips":["Monitor the IdP status page when 5xx bursts appear across multiple clients","Read the embedded response body in the message - it identifies which component failed","Do not misread this as a client misconfiguration; the request was well-formed"],"tags":["oauth2","device-flow","idp","http-5xx","network"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}