{"record":{"id":"f2b5b8a5db357faa","repo":"moeru-ai/airi","slug":"no-authorization-handler-is-registered-for-this-ap","errorCode":null,"errorMessage":"No authorization handler is registered for this app runtime.","messagePattern":"No authorization handler is registered for this app runtime\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/stage-ui/src/libs/auth.ts","lineNumber":117,"sourceCode":"    return false\n\n  const persisted = consumeFlowState()\n  if (!persisted)\n    throw new Error('OIDC flow status has expired or is no longer valid.')\n\n  const tokens = await exchangeCodeForTokens(code, persisted.flowState, persisted.params, state)\n  await applyOIDCTokens(tokens, persisted.params.clientId)\n  return true\n}\n\n/**\n * Initiate OIDC Authorization Code + PKCE sign-in flow.\n * Builds the authorization URL, persists PKCE state, and navigates.\n */\nexport async function signInOIDC(params: OIDCFlowParams) {\n  const handler = authorizationHandler\n  if (!handler)\n    throw new Error('No authorization handler is registered for this app runtime.')\n\n  const { provider, ...oidcParams } = params\n  const { url, flowState } = await buildAuthorizationURL(oidcParams)\n  persistFlowState(flowState, params)\n\n  const result = await handler({\n    authorizationUrl: url.toString(),\n    provider,\n  })\n  if (result?.callbackUrl)\n    await completeOIDCSignIn(result.callbackUrl)\n}\n\n/**\n * Trigger the project-default OIDC sign-in flow.\n *\n * Use when:\n * - Any UI surface needs to start a login (top-nav button, 401 handler,","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/moeru-ai/airi/blob/0616eabd5ba89c7bcef0eb1da84694b9c285c573/packages/stage-ui/src/libs/auth.ts#L99-L135","documentation":"signInOIDC requires a runtime-specific authorization handler (registered elsewhere for web vs Electron) that knows how to navigate to the provider's authorization URL. If no handler was set before sign-in, the library cannot navigate and throws immediately.","triggerScenarios":"Calling signInOIDC (directly or via triggerSignIn) before the app runtime registered its authorization handler (e.g. setAuthorizationHandler / initialization was skipped); running in an environment whose bootstrap code path never registers a handler; module initialization ordering issues where sign-in fires before app setup completes.","commonSituations":"Unit tests or Storybook harnesses that render a sign-in button without the app bootstrap; a new host app (Electron window, mobile webview) reusing stage-ui without wiring the handler; a refactor that moved handler registration into a lazily-loaded module; race where a deep-link auto-sign-in runs before setup.","solutions":["Register the authorization handler for your runtime before any sign-in call (find the app's auth bootstrap, e.g. where the Electron or web handler is installed).","If adding a new host/runtime, provide a handler that performs the navigation (window.location or Electron shell.openExternal) at startup.","Guard UI: disable the sign-in button until the auth runtime is initialized.","In tests, register a mock handler or assert the throw as expected pre-init behavior."],"exampleFix":"// before\nawait signInOIDC(params) // throws: no handler registered\n\n// after\n// during app bootstrap (once)\nsetAuthorizationHandler(async ({ url }) => {\n  window.location.assign(url)\n})\nawait signInOIDC(params)","handlingStrategy":"validation","validationCode":"if (!isAuthorizationHandlerRegistered()) { // expose a probe from the auth lib\n  disableSignInUI()\n} else {\n  enableSignInUI()\n}","typeGuard":"null","tryCatchPattern":"try {\n  await signInOIDC(params)\n} catch (err) {\n  if (err instanceof Error && err.message.includes('No authorization handler')) {\n    showSetupError('Sign-in is not configured for this runtime.')\n  } else throw err\n}","preventionTips":["Register the runtime authorization handler during app bootstrap, before any sign-in UI can be interacted with.","Disable sign-in controls until auth initialization completes.","Add a startup assertion/log that a handler is registered in every host app (web, Electron windows, tests).","Mock the handler in unit tests that exercise sign-in flows."],"tags":["oidc","auth","initialization","handler-registration"],"backgroundTag":"missing-runtime-handler","analyzedSha":"0616eabd5ba89c7bcef0eb1da84694b9c285c573","analyzedAt":"2026-08-28T13:11:01.995Z","contentChangedAt":"2026-08-28T13:11:01.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}