{"record":{"id":"e4dcfc41480e7c5e","repo":"tinyhumansai/openhuman","slug":"oauthauthreadinessusermessage-quick-reason","errorCode":null,"errorMessage":"oauthAuthReadinessUserMessage(quick.reason)","messagePattern":"oauthAuthReadinessUserMessage\\(quick\\.reason\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/src/components/oauth/oauthAuthReadiness.ts","lineNumber":165,"sourceCode":"        'OpenHuman could not reach its local runtime. Quit and reopen the app, ' +\n        'then try signing in again.'\n      );\n    }\n    default:\n      return 'Sign-in is still starting up. Wait a few seconds and try again.';\n  }\n}\n\n/**\n * Lightweight preflight before opening the system browser for OAuth.\n * Blocks browser launch when the local auth runtime is not ready yet.\n * `waitForOAuthAuthReadiness()` starts the local core when needed.\n */\nexport async function prepareOAuthLoginLaunch(): Promise<void> {\n  const quick = await waitForOAuthAuthReadiness(8_000);\n  if (!quick.ready) {\n    warnLog(`${logPrefix} pre-launch readiness`, quick);\n    throw new Error(oauthAuthReadinessUserMessage(quick.reason));\n  }\n}\n","sourceCodeStart":147,"sourceCodeEnd":168,"githubUrl":"https://github.com/tinyhumansai/openhuman/blob/749120085864ce16e0f273c7b86fac7740b39c5b/app/src/components/oauth/oauthAuthReadiness.ts#L147-L168","documentation":"Thrown by prepareOAuthLoginLaunch() after an 8-second preflight waiting for the local OpenHuman core to become ready before opening the system browser for OAuth. waitForOAuthAuthReadiness() polls core RPC reachability and core-mode selection; if either fails within the budget it returns {ready:false, reason}, and this line converts the reason into a human-readable message via oauthAuthReadinessUserMessage(). The reason is either 'core_mode_unset' (user never finished setup mode selection) or 'core_unreachable' (RPC ping failed after the deadline).","triggerScenarios":"Calling prepareOAuthLoginLaunch() when (a) the stored core mode has not been chosen yet (getStoredCoreMode() unset, e.g. fresh install before onboarding completes), or (b) the local core process fails to start or its HTTP RPC endpoint at 127.0.0.1:<port>/rpc never answers pings within 8000ms, or (c) cloud mode is selected but the remote runtime URL/token is wrong so pingCoreRpc() keeps failing.","commonSituations":"Fresh install where the user clicks 'Sign in' before finishing the setup screen; core startup slowed by cold start, antivirus scanning the binary, or a stuck update; a crashed/zombie core process from a previous session holding the port; cloud mode configured with a stale RPC URL or expired OPENHUMAN_CORE_TOKEN; CI/test environments with no core binary available.","solutions":["If the message mentions choosing how OpenHuman runs: finish the setup/onboarding screen (select local or cloud mode) and retry sign-in.","If local runtime unreachable: fully quit the app (verify no openhuman-core process lingers in Task Manager/Activity Monitor) and reopen, then retry.","If cloud runtime unreachable: check Settings for the correct RPC URL and token, re-enter them, and retry.","Give the core more than 8s on slow machines — retry the sign-in action after a few seconds; if it persists, inspect core logs for startup crashes.","Developers: call waitForOAuthAuthReadiness() with a larger maxWaitMs or catch this error and surface a retry UI instead of a dead-end."],"exampleFix":"// before\nawait prepareOAuthLoginLaunch(); // throws after fixed 8s budget\nopenSystemBrowser(authUrl);\n\n// after\nconst ready = await waitForOAuthAuthReadiness(20_000);\nif (!ready.ready) {\n  showRetryableNotice(oauthAuthReadinessUserMessage(ready.reason));\n  return;\n}\nopenSystemBrowser(authUrl);","handlingStrategy":"retry","validationCode":"import { waitForOAuthAuthReadiness } from './oauthAuthReadiness';\n\nconst ready = await waitForOAuthAuthReadiness(8000);\nif (!ready.ready) {\n  // show reason-specific guidance, offer retry\n}","typeGuard":"type Readiness =\n  | { ready: true }\n  | { ready: false; reason: 'core_mode_unset' | 'core_unreachable' };","tryCatchPattern":"try {\n  await prepareOAuthLoginLaunch();\n} catch (err) {\n  // err.message is already user-facing copy from oauthAuthReadinessUserMessage()\n  showNotice(err.message, { action: 'retry' });\n}","preventionTips":["Call waitForOAuthAuthReadiness() yourself with a longer budget on slow machines before invoking the preflight.","Ensure onboarding (core mode selection) is complete before enabling the sign-in button.","In dev, confirm the core binary exists and starts (core_process logs) before opening OAuth."],"tags":["oauth","startup","core-rpc","timeout","readiness"],"backgroundTag":"service-startup-timeout","analyzedSha":"749120085864ce16e0f273c7b86fac7740b39c5b","analyzedAt":"2026-08-17T21:21:45.363Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}