{"record":{"id":"9e5beb32c5998f29","repo":"Stirling-Tools/Stirling-PDF","slug":"unable-to-open-system-browser-for-sso-please-chec","errorCode":null,"errorMessage":"Unable to open system browser for SSO. Please check your system settings.","messagePattern":"Unable to open system browser for SSO\\. Please check your system settings\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/desktop/services/authService.ts","lineNumber":1043,"sourceCode":"\n    const trimmedServer = serverUrl.replace(/\\/+$/, \"\");\n    const fullUrl = providerPath.startsWith(\"http\")\n      ? providerPath\n      : `${trimmedServer}${providerPath.startsWith(\"/\") ? providerPath : `/${providerPath}`}`;\n    let authUrl = fullUrl;\n    try {\n      const parsed = new URL(fullUrl);\n      parsed.searchParams.set(\"tauri\", \"1\");\n      parsed.searchParams.set(\"nonce\", nonce);\n      authUrl = parsed.toString();\n    } catch {\n      // ignore URL parsing failures\n    }\n\n    // Register deep-link listener before opening browser to avoid callback races on first launch.\n    return this.waitForDeepLinkCompletion(trimmedServer, async () => {\n      if (!(await this.openInSystemBrowser(authUrl))) {\n        throw new Error(\n          \"Unable to open system browser for SSO. Please check your system settings.\",\n        );\n      }\n    });\n  }\n\n  /**\n   * Wait for a deep-link event to complete self-hosted SSO after system browser OAuth\n   */\n  private async waitForDeepLinkCompletion(\n    serverUrl: string,\n    startFlow?: () => Promise<void>,\n  ): Promise<UserInfo> {\n    if (!isTauri()) {\n      throw new Error(\n        \"Deep link authentication is only supported in Tauri desktop app.\",\n      );\n    }","sourceCodeStart":1025,"sourceCodeEnd":1061,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/desktop/services/authService.ts#L1025-L1061","documentation":"Thrown by loginWithSelfHostedOAuth when openInSystemBrowser(authUrl) resolves to false — the OS 'open URL' shell call declined/failed, so the SSO authorization page could never be shown to the user. The deep-link wait never starts because the browser step failed first.","triggerScenarios":"Tauri's shell.open (or the platform equivalent) returns false/throws: no default browser configured, the browser binary is missing or quarantined, an OS policy blocks opening external URLs, or the URL scheme is disallowed.","commonSituations":"Kiosk/locked-down machine with no default browser set; enterprise policy forbidding launching external apps; a browser binary that was uninstalled; sandboxed environment where shell.open is denied.","solutions":["Set a default web browser in the OS settings and retry.","Allow the desktop app to open external URLs (relax the OS/app-store policy that blocks it).","As a fallback, copy the authUrl to the clipboard and have the user paste it into a browser manually.","Verify the configured OAuth providerPath resolves to a full https:// URL before opening."],"exampleFix":"// before: only throw on failure\nif (!(await this.openInSystemBrowser(authUrl))) {\n  throw new Error('Unable to open system browser for SSO…');\n}\n\n// after: fall back to clipboard copy + manual open\nif (!(await this.openInSystemBrowser(authUrl))) {\n  await writeText(authUrl);\n  notify('Could not open the browser. We copied the sign-in link — paste it into your browser.');\n}","handlingStrategy":"fallback","validationCode":"// validate the OAuth URL is well-formed before opening\nfunction isValidAuthUrl(u: string): boolean { try { const p = new URL(u); return p.protocol === 'http:' || p.protocol === 'https:'; } catch { return false; } }","typeGuard":"function isBrowserOpenFailure(e: unknown): e is Error {\n  return e instanceof Error && /Unable to open system browser/.test(e.message);\n}","tryCatchPattern":"try { await authService.loginWithSelfHostedOAuth(providerPath, serverUrl); }\ncatch (e) {\n  if (isBrowserOpenFailure(e)) { await writeText(authUrl); notify('We copied the sign-in link — open it in your browser.'); return; }\n  throw e;\n}","preventionTips":["Provide a clipboard-copy fallback when the system browser can't open.","Verify a default browser is set in the OS before SSO.","Construct the OAuth URL with new URL() so a malformed providerPath never reaches shell.open."],"tags":["authentication","sso","oauth","browser","desktop"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}