{"record":{"id":"5891fcccbb5379b4","repo":"paperclipai/paperclip","slug":"unavailable","errorCode":"unavailable","errorMessage":"Paperclip Cloud couldn’t prepare secure sign-in. Try again.","messagePattern":"Paperclip Cloud couldn’t prepare secure sign-in\\. Try again\\.","errorType":"exception","errorClass":"OAuthHandoffError","httpStatus":null,"severity":"error","filePath":"ui/src/lib/oauthHandoff.ts","lineNumber":86,"sourceCode":"  let lastError: unknown;\n  for (let attempt = 0; attempt < 2; attempt += 1) {\n    try {\n      response = await request(CLOUD_HANDOFF_PATH, {\n        method: \"POST\",\n        headers: { \"content-type\": \"application/json\", accept: \"application/json\" },\n        credentials: \"include\",\n        body: JSON.stringify({ session }),\n        signal: options.signal,\n      });\n      if (response.status < 500 || attempt === 1) return response;\n    } catch (error) {\n      if (options.signal?.aborted || (error instanceof DOMException && error.name === \"AbortError\")) throw error;\n      lastError = error;\n      if (attempt === 1) break;\n    }\n  }\n  if (response) return response;\n  throw new OAuthHandoffError(\n    lastError instanceof Error ? lastError.message : \"Paperclip Cloud couldn’t prepare secure sign-in. Try again.\",\n    \"unavailable\",\n  );\n}\n\nfunction exactReauthenticationTarget(value: unknown, session: string): PreparedOAuthNavigation | null {\n  if (typeof value !== \"string\" || typeof window === \"undefined\") return null;\n  try {\n    const url = new URL(value, window.location.origin);\n    if (\n      url.origin !== window.location.origin\n      || url.pathname !== CLOUD_REAUTH_PATH\n      || url.username\n      || url.password\n      || url.hash\n      || url.searchParams.size !== 1\n      || url.searchParams.get(\"session\") !== session\n    ) return null;","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/ui/src/lib/oauthHandoff.ts#L68-L104","documentation":"postCloudHandoff retries its POST to the Paperclip Cloud handoff endpoint; if every attempt fails at the network level (fetch threw) and no response was ever obtained, it throws OAuthHandoffError with code \"unavailable\". The message falls back to the last underlying error message when available, otherwise this generic guidance string.","triggerScenarios":"Both fetch attempts to the cloud handoff endpoint threw (network down, DNS failure, CORS block, request aborted by something other than the caller's signal), leaving `response` null.","commonSituations":"User offline or on a captive portal; Paperclip Cloud endpoint unreachable; ad-blocker/extension blocking the request; mixed-content or CORS misconfiguration in a dev environment.","solutions":["Check network connectivity and reachability of the Paperclip Cloud endpoint, then retry sign-in.","Disable browser extensions/ad-blockers that may block the request and retry.","Inspect the underlying `lastError` (the OAuthHandoffError message carries it) for the real cause.","If it persists, verify the cloud handoff service status/endpoint configuration."],"exampleFix":"// before\nawait prepareOAuthNavigation(start); // raw throw surfaces to user\n// after\ntry {\n  await prepareOAuthNavigation(start);\n} catch (e) {\n  if (e instanceof OAuthHandoffError && e.code === \"unavailable\") {\n    showRetryBanner(\"Network unavailable — retry sign-in\");\n  } else throw e;\n}","handlingStrategy":"retry","validationCode":"if (typeof navigator !== \"undefined\" && !navigator.onLine) {\n  showOfflineBanner(); return; // skip the request entirely\n}","typeGuard":null,"tryCatchPattern":"try {\n  await prepareOAuthNavigation(start, { signal });\n} catch (e) {\n  if (e instanceof OAuthHandoffError && e.code === \"unavailable\") {\n    scheduleRetryWithBackoff(() => prepareOAuthNavigation(start, { signal }));\n  } else throw e;\n}","preventionTips":["Check navigator.onLine and gate sign-in on connectivity.","Retry transient network failures with exponential backoff before surfacing the error.","Monitor the cloud handoff endpoint's availability; alert on rising failure rates.","Preserve the underlying lastError message for diagnostics rather than showing only the generic text."],"tags":["network","oauth","fetch-failed","retry-exhausted"],"backgroundTag":"network-request-failed","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}