toeverything/AFFiNE · error · UnknownOauthProvider

unknown_oauth_provider

unknown_oauth_provider

Error message

Unknown authentication provider ${name}.

What it means

UnknownOauthProvider thrown at packages/backend/server/src/plugins/oauth/service.ts:125 when the state record names a provider that OAuthProviderFactory.get() cannot find. Providers register themselves at startup only when their config is valid (e.g. the OIDC provider registers after successful discovery), so the lookup fails when the provider disappeared between preflight and callback or was never configured.

Source

Thrown at packages/backend/server/src/plugins/oauth/service.ts:125

      state.client !== 'web'
    ) {
      return {
        type: 'handoff',
        code: input.code,
        provider: rawState.provider,
        state,
        stateToken: stateStr,
      };
    }

    if (!state.provider) {
      throw new MissingOauthQueryParameter({ name: 'provider' });
    }

    const provider = this.providerFactory.get(state.provider);

    if (!provider) {
      throw new UnknownOauthProvider({ name: state.provider ?? 'unknown' });
    }

    if (
      state.provider !== OAuthProviderName.Apple &&
      (!input.clientNonce ||
        !state.clientNonce ||
        state.clientNonce !== input.clientNonce)
    ) {
      throw new InvalidAuthState();
    }

    return {
      type: 'identity',
      identity: await this.verifyCallbackIdentity(
        input.code,
        state,
        stateStr,
        input.rawBody

View on GitHub (pinned to b4c8548c09)

Solutions

1. Check server startup logs for 'OAuth provider [oidc] registered.' or discovery validation errors ('Failed to validate OIDC configuration').
2. Restore/fix the provider config (oauth.providers.oidc.clientId/clientSecret/issuer) and restart.
3. If discovery is failing due to a private-network issuer, set allowPrivateNetwork: true for the issuer origin.
4. Have the user restart the login flow after the provider is registered again.

// Pre-flight the provider before the user starts login
const provider = providerFactory.get(stateProviderName);
if (!provider) {
  throw new Error(`Provider ${stateProviderName} not registered - check startup config`);
}

try {
  await oauth.verifyCallback(input);
} catch (err) {
  if (err instanceof UnknownOauthProvider) {
    // provider unregistered since login started: check config/startup logs, then restart flow
  }
}

When it happens

Trigger: User starts OIDC login, the server restarts with oauth.providers.oidc.* env/config removed or invalid (discovery failed, so the provider is unregistered), then the callback arrives; state saved under a provider name string that no longer matches a registered enum; config hot-reload disabling the provider mid-flow.

Common situations: Self-hoster changes OAUTH env vars or rotates to a config where the issuer is unreachable (OIDC discovery validation failed and retried, leaving the provider unregistered); typo in provider name in a custom preflight call; mixed-version rolling deploy where a node lacks the provider.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• unknown_oauth_provider
• missing_oauth_query_parameter
• sign_up_forbidden
• Invalid value "${value}" for environment variable ${env}, ex
• Invalid NODE_ENV environment. `${this.NODE_ENV}` is not a va

AI-assisted analysis of toeverything/AFFiNE@b4c8548c09 (2026-08-18). Data as JSON: /api/errors/5e7afbedaa1d06a9. Report an issue: GitHub.