{"record":{"id":"989b1e532ba98e29","repo":"upstash/context7","slug":"could-not-reach-url-detail-code-code-n-hint","errorCode":null,"errorMessage":"Could not reach ${url}: ${detail}${code ? ` (${code})` : \"\"}\\n${hint}","messagePattern":"Could not reach (.+?): (.+?)(.+?)\\)` : \"\"\\}\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/auth.ts","lineNumber":221,"sourceCode":"}\n\nfunction describeConnectionError(error: unknown, url: string): string {\n  const { code, message } = getErrorCause(error);\n  const detail = message || (error instanceof Error ? error.message : String(error));\n  const hint = (code && CONNECTION_HINTS[code]) || DEFAULT_HINT;\n\n  return `Could not reach ${url}: ${detail}${code ? ` (${code})` : \"\"}\\n${hint}`;\n}\n\nasync function postForm(url: string, params: URLSearchParams): Promise<Response> {\n  try {\n    return await fetch(url, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n      body: params.toString(),\n    });\n  } catch (error) {\n    throw new Error(describeConnectionError(error, url));\n  }\n}\n\nasync function oauthRequest<T>(url: string, params: URLSearchParams, fallback: string): Promise<T> {\n  const response = await postForm(url, params);\n  if (!response.ok) {\n    throw new Error(await describeErrorResponse(response, fallback));\n  }\n  return (await response.json()) as T;\n}\n\n/** RFC 8628 §3.2 default poll interval when the server omits `interval`. */\nexport const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;\n\nexport async function startDeviceAuthorization(\n  baseUrl: string,\n  clientId: string\n): Promise<DeviceAuthorizationResponse> {","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/upstash/context7/blob/4416fb855b8f752be735e34f943b5d0762701aad/packages/cli/src/utils/auth.ts#L203-L239","documentation":"Thrown by postForm when the underlying fetch to an OAuth endpoint (token exchange, device authorization, refresh) fails at the network level — DNS failure, connection refused, timeout, TLS error, etc. The raw fetch error is passed to describeConnectionError, which produces a human-readable message including the URL, the failure detail, the optional error code, and a hint. This converts opaque undici/network errors into actionable messages for CLI users.","triggerScenarios":"Any OAuth flow call (oauthRequest, pollDeviceToken, token refresh) that invokes postForm while the auth server is unreachable: offline machine, wrong base URL, DNS misconfiguration, blocked firewall/proxy, or the auth server being down.","commonSituations":"Corporate proxies intercepting TLS, VPN required to reach the auth host, typo'd domain in auth configuration, no internet in CI, or transient server outage during device-code login.","solutions":["Check network connectivity and retry the login/command","Verify the auth base URL is correct and resolvable (the URL in the message tells you which host failed)","Check proxy/VPN/firewall settings — set HTTPS_PROXY if your network requires it, or allowlist the auth domain","Check the auth service status or retry later if it's a server-side outage"],"exampleFix":"// before: failing in a proxied environment\nawait fetch(url, { method: \"POST\", body: params.toString() });\n// after: rely on proxy env vars / add timeout handling\nawait fetch(url, {\n  method: \"POST\",\n  body: params.toString(),\n  signal: AbortSignal.timeout(15000),\n});","handlingStrategy":"retry","validationCode":"// probe reachability before the OAuth call\ntry {\n  await fetch(baseUrl, { method: \"HEAD\", signal: AbortSignal.timeout(5000) });\n} catch (e) {\n  throw new Error(`Auth server unreachable at ${baseUrl}: ${e.cause?.code ?? e.message}`);\n}","typeGuard":null,"tryCatchPattern":"let lastErr;\nfor (let attempt = 0; attempt < 3; attempt++) {\n  try { return await startOAuthFlow(); }\n  catch (e) {\n    lastErr = e;\n    if (!/Could not reach/.test(e.message)) throw e; // only retry network errors\n    await new Promise(r => setTimeout(r, 2 ** attempt * 1000));\n  }\n}\nthrow lastErr;","preventionTips":["Check connectivity/proxy env (HTTPS_PROXY) before auth flows in CI","Configure request timeouts so failures fail fast with clear causes","Monitor auth service status; surface the URL from the error message to users"],"tags":["network","oauth","fetch","cli"],"backgroundTag":"network-request-failed","analyzedSha":"4416fb855b8f752be735e34f943b5d0762701aad","analyzedAt":"2026-09-16T20:28:07.148Z","contentChangedAt":"2026-09-16T20:28:07.148Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}