{"record":{"id":"a994fad48af82476","repo":"eyaltoledano/claude-task-master","slug":"start-flow-failed","errorCode":"START_FLOW_FAILED","errorMessage":"startResponse.message || 'Failed to start authentication flow'","messagePattern":"startResponse\\.message \\|\\| 'Failed to start authentication flow'","errorType":"error_code","errorClass":"AuthenticationError","httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/auth/services/oauth-service.ts","lineNumber":162,"sourceCode":"\t\toptions: OAuthFlowOptions\n\t): Promise<AuthCredentials> {\n\t\tconst {\n\t\t\topenBrowser,\n\t\t\ttimeout = 300000,\n\t\t\tonAuthUrl,\n\t\t\tonWaitingForAuth,\n\t\t\tonSuccess\n\t\t} = options;\n\n\t\t// Step 1: Generate keypair for E2E encryption\n\t\tthis.keyPair = generateKeyPair();\n\t\tthis.logger.debug('Generated RSA keypair for E2E encryption');\n\n\t\t// Step 2: Start the flow on the backend with our public key\n\t\tconst startResponse = await this.startBackendFlow();\n\n\t\tif (!startResponse.success || !startResponse.flow_id) {\n\t\t\tthrow new AuthenticationError(\n\t\t\t\tstartResponse.message || 'Failed to start authentication flow',\n\t\t\t\t'START_FLOW_FAILED'\n\t\t\t);\n\t\t}\n\n\t\tconst { flow_id, verification_url, poll_interval = 2 } = startResponse;\n\n\t\t// Store the auth URL\n\t\tthis.authorizationUrl = verification_url || null;\n\n\t\t// Notify about the auth URL\n\t\tif (onAuthUrl && verification_url) {\n\t\t\tonAuthUrl(verification_url);\n\t\t}\n\n\t\t// Step 3: Open browser with verification URL\n\t\tif (openBrowser && verification_url) {\n\t\t\ttry {","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/auth/services/oauth-service.ts#L144-L180","documentation":"During authenticateWithBackendPKCE the client generates an RSA keypair, then asks the backend to start a PKCE auth flow (startBackendFlow). If the backend response is unsuccessful or lacks a flow_id, the client throws AuthenticationError with code START_FLOW_FAILED, using the backend's message when provided.","triggerScenarios":"POST to `${baseUrl}/api/auth/cli/start` returns success=false, an error payload, or a 2xx body without flow_id — e.g. backend outage, unsupported server version, rate limiting, or wrong base URL hitting an unexpected endpoint.","commonSituations":"Pointing tm at a stale/mismatched backend URL; API server down or deployed with a different auth API; corporate proxy intercepting the request; backend rate-limits repeated login attempts.","solutions":["Verify the backend base URL/configuration is correct and the server is reachable (curl the /api/auth/cli/start endpoint)","Check the thrown message for backend-provided details and follow them","Retry after a short delay if it was transient (5xx/network); check backend service health","Update the CLI if the backend auth API version changed","Catch AuthenticationError code START_FLOW_FAILED and surface startResponse.message to the user"],"exampleFix":"// before\nawait auth.authenticate(); // opaque START_FLOW_FAILED\n// after\ntry {\n  await auth.authenticate();\n} catch (e) {\n  if (e instanceof AuthenticationError && e.code === 'START_FLOW_FAILED') {\n    console.error('Auth backend rejected flow start:', e.message);\n  }\n  throw e;\n}","handlingStrategy":"retry","validationCode":"// preflight: confirm the auth backend is reachable\nconst res = await fetch(`${baseUrl}/api/auth/cli/start`, { method: 'HEAD' }).catch(() => null);\nif (!res) throw new Error('Auth backend unreachable at ' + baseUrl);","typeGuard":"function isStartFlowFailed(e: unknown): e is AuthenticationError {\n  return e instanceof AuthenticationError && e.code === 'START_FLOW_FAILED';\n}","tryCatchPattern":"for (let i = 0; i < 3; i++) {\n  try { await auth.authenticate(); break; }\n  catch (e) {\n    if (isStartFlowFailed(e) && i < 2) { await sleep(2000 * (i + 1)); continue; }\n    throw e;\n  }\n}","preventionTips":["Verify the backend base URL matches the deployed API version","Add a reachability preflight before login flows","Implement bounded retries with backoff for transient backend failures","Surface the backend-provided message (startResponse.message) in CLI output for diagnostics"],"tags":["auth","oauth","network","backend"],"backgroundTag":"auth-flow-start-failed","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}