{"record":{"id":"e30e9863b262b54e","repo":"mastra-ai/mastra","slug":"poll-failed-err-detail-resp-statustext","errorCode":null,"errorMessage":"Poll failed: ${err.detail || resp.statusText}","messagePattern":"Poll failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/deploy/index.ts","lineNumber":510,"sourceCode":"    while (Date.now() - start < maxWaitMs) {\n      const resp = await fetch(url, {\n        headers: {\n          Authorization: `Bearer ${currentToken}`,\n          'x-organization-id': orgId,\n        },\n      });\n\n      if (resp.status === 401) {\n        currentToken = await getToken();\n        // Back off before retrying so a persistently-401 token cannot spin\n        // the poll loop into a tight retry storm against the platform API.\n        await new Promise(r => setTimeout(r, 2000));\n        continue;\n      }\n\n      if (!resp.ok) {\n        const err = (await resp.json().catch(() => ({}))) as { detail?: string };\n        throw new Error(`Poll failed: ${err.detail || resp.statusText}`);\n      }\n\n      const { deploy } = (await resp.json()) as { deploy: UnifiedDeployStatus };\n\n      if (deploy.status === 'running' || deploy.status === 'failed' || deploy.status === 'stopped') {\n        return deploy;\n      }\n\n      await new Promise(r => setTimeout(r, 2000));\n    }\n\n    throw new Error('Deploy timed out');\n  } finally {\n    logAbort.abort();\n  }\n}\n\n/* ------------------------------------------------------------------ */","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/deploy/index.ts#L492-L528","documentation":"Thrown by pollEnvironmentDeploy when a status-poll HTTP request to the deploy API returns a non-ok response. The CLI polls every 2 seconds for the deploy status; if any poll request fails (e.g. 500 or 401), it aborts polling and surfaces the server's `detail` message or the HTTP status text. This means the deploy status could not be determined, not necessarily that the deploy itself failed.","triggerScenarios":"An intermediate poll response has resp.ok === false (any non-2xx status). The error message contains err.detail parsed from the response JSON body, or resp.statusText if the body has no detail field.","commonSituations":"Expired or revoked MASTRA_API_TOKEN mid-deploy (401); transient server 5xx during a long-running deploy poll; API gateway timeouts or rate limiting (429); network proxy interruptions returning HTML error pages.","solutions":["Check the detail message in the error to see the exact API failure reason (auth, rate limit, server error).","If it is a 401/403, regenerate the API token and re-export MASTRA_API_TOKEN, then retry the deploy.","For transient 5xx/429, wait and re-run `mastra deploy`; poll failures are not necessarily fatal to the remote deploy.","Verify network/proxy settings allow sustained access to the Mastra API for the duration of the deploy."],"exampleFix":"// before: retries never handled, any failed poll aborts\nthrow new Error(`Poll failed: ${err.detail || resp.statusText}`);\n// after: tolerate transient poll failures with a bounded retry\nif (!resp.ok && resp.status >= 500 && transientFailures < 3) {\n  transientFailures++;\n  await new Promise(r => setTimeout(r, 2000));\n  continue;\n}\nthrow new Error(`Poll failed: ${err.detail || resp.statusText}`);","handlingStrategy":"retry","validationCode":"// preflight the token before deploying\ncurl -s -o /dev/null -w '%{http_code}' -H \"Authorization: Bearer $MASTRA_API_TOKEN\" https://api.mastra.ai/...","typeGuard":null,"tryCatchPattern":"try {\n  await deployAndPoll();\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Poll failed:')) {\n    // inspect detail, optionally retry with backoff\n    console.error('Deploy status polling failed:', e.message);\n  } else throw e;\n}","preventionTips":["Use a long-lived, correctly scoped API token for CI deploys.","Ensure stable network access (no aggressive proxies) for the whole deploy duration.","Handle 429/5xx responses with retries rather than assuming deploy failure.","Log the poll failure detail to distinguish auth vs server errors."],"tags":["network","http","deploy","polling"],"backgroundTag":"deploy-status-poll-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}