eyaltoledano/claude-task-master · error · AuthenticationError

BACKEND_UNREACHABLE

BACKEND_UNREACHABLE

Error message

Unable to reach authentication server

What it means

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.

Source

Thrown at packages/tm-core/src/modules/auth/services/oauth-service.ts:298

			if (!response.ok) {
				const errorData = (await response.json().catch(() => ({}))) as {
					message?: string;
				};
				throw new AuthenticationError(
					errorData.message || `HTTP ${response.status}`,
					'START_FLOW_FAILED'
				);
			}

			return (await response.json()) as StartFlowResponse;
		} catch (error) {
			if (error instanceof AuthenticationError) {
				throw error;
			}

			// Network errors indicate backend is unreachable
			this.logger.warn('Failed to reach backend for PKCE flow:', error);
			throw new AuthenticationError(
				'Unable to reach authentication server',
				'BACKEND_UNREACHABLE',
				error
			);
		}
	}

	/**
	 * Poll the backend for flow completion
	 */
	private async pollForCompletion(
		flowId: string,
		pollInterval: number,
		timeout: number
	): Promise<AuthCredentials> {
		const statusUrl = `${this.baseUrl}/api/auth/cli/status?flow_id=${flowId}`;
		const startTime = Date.now();

View on GitHub (pinned to c0c98d367c)

Solutions

1. Confirm the auth server is reachable: curl the baseUrl health endpoint from the same machine.
2. Verify the base URL and port configured for authentication (CLI config / environment variables).
3. Check DNS and proxies: try the URL in a browser, set HTTPS_PROXY if a corporate proxy is required.
4. If running self-hosted, confirm the auth backend container/service is running and listening.
5. Fix TLS trust (install the corporate CA or correct the certificate) if the error is certificate-related.

Example fix

// before
const auth = new OAuthService({ baseUrl: 'http://localhost:9999' }); // nothing listening
// after
const auth = new OAuthService({ baseUrl: process.env.TM_AUTH_URL || 'https://auth.example.com' });
// verify first: curl -I https://auth.example.com/health

let reachable = false;
try {
  reachable = (await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) })).ok;
} catch { reachable = false; }
if (!reachable) throw new Error(`Auth server unreachable at ${baseUrl}`);

function isAuthBackendUnreachable(e: unknown): e is AuthenticationError {
  return e instanceof AuthenticationError && (e as any).code === 'BACKEND_UNREACHABLE';
}

try {
  await oauth.startBackendFlow();
} catch (e) {
  if (isAuthBackendUnreachable(e)) {
    console.error('Cannot reach auth server — check network/VPN and baseUrl:', e.cause ?? e.message);
  }
}

When it happens

Trigger: startBackendFlow's fetch throws (not response.ok): invalid/unresolvable hostname, server down, firewall blocking, TLS certificate error, or request timeout.

Common situations: 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.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• START_FLOW_FAILED
• FLOW_NOT_FOUND
• POLL_FAILED
• MISSING_TOKENS
• OAUTH_FAILED

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/9e79f9b2f9b65717. Report an issue: GitHub.