{"record":{"id":"9e79f9b2f9b65717","repo":"eyaltoledano/claude-task-master","slug":"backend-unreachable","errorCode":"BACKEND_UNREACHABLE","errorMessage":"Unable to reach authentication server","messagePattern":"Unable to reach authentication server","errorType":"error_code","errorClass":"AuthenticationError","httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/auth/services/oauth-service.ts","lineNumber":298,"sourceCode":"\t\t\tif (!response.ok) {\n\t\t\t\tconst errorData = (await response.json().catch(() => ({}))) as {\n\t\t\t\t\tmessage?: string;\n\t\t\t\t};\n\t\t\t\tthrow new AuthenticationError(\n\t\t\t\t\terrorData.message || `HTTP ${response.status}`,\n\t\t\t\t\t'START_FLOW_FAILED'\n\t\t\t\t);\n\t\t\t}\n\n\t\t\treturn (await response.json()) as StartFlowResponse;\n\t\t} catch (error) {\n\t\t\tif (error instanceof AuthenticationError) {\n\t\t\t\tthrow error;\n\t\t\t}\n\n\t\t\t// Network errors indicate backend is unreachable\n\t\t\tthis.logger.warn('Failed to reach backend for PKCE flow:', error);\n\t\t\tthrow new AuthenticationError(\n\t\t\t\t'Unable to reach authentication server',\n\t\t\t\t'BACKEND_UNREACHABLE',\n\t\t\t\terror\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Poll the backend for flow completion\n\t */\n\tprivate async pollForCompletion(\n\t\tflowId: string,\n\t\tpollInterval: number,\n\t\ttimeout: number\n\t): Promise<AuthCredentials> {\n\t\tconst statusUrl = `${this.baseUrl}/api/auth/cli/status?flow_id=${flowId}`;\n\t\tconst startTime = Date.now();\n","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/auth/services/oauth-service.ts#L280-L316","documentation":"AuthenticationError thrown when the flow-start request fails before an HTTP response is obtained — i.e. a network-level failure (DNS, connection refused, TLS, timeout). The library rethrows AuthenticationError unchanged, wraps any other error as BACKEND_UNREACHABLE, and logs a warning indicating the backend could not be reached for the PKCE flow.","triggerScenarios":"startBackendFlow's fetch throws (not response.ok): invalid/unresolvable hostname, server down, firewall blocking, TLS certificate error, or request timeout.","commonSituations":"Offline or VPN-required network; wrong baseUrl/port in CLI config or TM_BASE_URL env var; auth service crashed or not yet deployed; corporate proxy intercepting HTTPS; self-signed cert without trusted CA.","solutions":["Confirm the auth server is reachable: curl the baseUrl health endpoint from the same machine.","Verify the base URL and port configured for authentication (CLI config / environment variables).","Check DNS and proxies: try the URL in a browser, set HTTPS_PROXY if a corporate proxy is required.","If running self-hosted, confirm the auth backend container/service is running and listening.","Fix TLS trust (install the corporate CA or correct the certificate) if the error is certificate-related."],"exampleFix":"// before\nconst auth = new OAuthService({ baseUrl: 'http://localhost:9999' }); // nothing listening\n// after\nconst auth = new OAuthService({ baseUrl: process.env.TM_AUTH_URL || 'https://auth.example.com' });\n// verify first: curl -I https://auth.example.com/health","handlingStrategy":"retry","validationCode":"let reachable = false;\ntry {\n  reachable = (await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) })).ok;\n} catch { reachable = false; }\nif (!reachable) throw new Error(`Auth server unreachable at ${baseUrl}`);","typeGuard":"function isAuthBackendUnreachable(e: unknown): e is AuthenticationError {\n  return e instanceof AuthenticationError && (e as any).code === 'BACKEND_UNREACHABLE';\n}","tryCatchPattern":"try {\n  await oauth.startBackendFlow();\n} catch (e) {\n  if (isAuthBackendUnreachable(e)) {\n    console.error('Cannot reach auth server — check network/VPN and baseUrl:', e.cause ?? e.message);\n  }\n}","preventionTips":["Verify connectivity to baseUrl (curl/health check) before attempting login","Check VPN, firewall, and corporate proxy settings when working remotely","Inspect e.cause — it contains the underlying network error (DNS/TLS/refused)","Validate baseUrl and port in CLI config / environment variables"],"tags":["network","connection","oauth","unreachable"],"backgroundTag":"connection-refused","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}