Failed to load OAuth metadata. (formatOauthFetchFailure with

Error message

Failed to load OAuth metadata. (formatOauthFetchFailure with envName, baseUrl, url, rawMessage)

What it means

fetchOauthServerMetadata fetches the OAuth authorization-server metadata document (via getOauthMetadataUrl from the configured baseUrl). If the underlying fetchWithOauthRetry call throws after all retries (network failure, timeout), the error is re-wrapped with formatOauthFetchFailure, producing this message plus env name, baseUrl, the metadata URL, and the raw network error.

Source

Thrown at packages/core/cli/src/lib/env-auth.ts:342

}

async function fetchOauthServerMetadata(
  baseUrl: string,
  options: { envName?: string; onRetry?: (message: string) => void } = {},
) {
  const metadataUrl = getOauthMetadataUrl(baseUrl);
  let response: Response;
  try {
    response = await fetchWithOauthRetry(
      metadataUrl,
      undefined,
      {
        operation: 'Loading OAuth metadata',
        onRetry: options.onRetry,
      },
    );
  } catch (error: any) {
    throw new Error(
      formatOauthFetchFailure('Failed to load OAuth metadata.', {
        envName: options.envName,
        baseUrl,
        url: metadataUrl,
        rawMessage: error?.message,
      }),
    );
  }
  const data = await parseJsonResponse(response);

  if (!response.ok) {
    throw new Error(formatOauthError(`Failed to load OAuth metadata from ${metadataUrl}`, data, response.status));
  }

  if (
    !data ||
    typeof data !== 'object' ||
    typeof data.issuer !== 'string' ||

View on GitHub (pinned to fa42722fef)

Solutions

Verify the environment's baseUrl is reachable: `curl <baseUrl>/.well-known/oauth-authorization-server` (or the metadata path the CLI uses)
Correct the baseUrl in your environment config if it is wrong
Ensure the NocoBase server is running and the OAuth discovery endpoint is served at the expected path
Check proxies/VPN/firewall if curl also fails to connect

Example fix

// before
nocobase env use prod   # baseUrl: https://nocobase.example.co: wrong TLD/port
// after
fix baseUrl to https://nocobase.example.com then retry sign-in

Defensive patterns

Strategy: try-catch

Validate before calling

const base = new URL(baseUrl); // validate scheme/host
const resp = await fetch(new URL('/.well-known/oauth-authorization-server', base), { signal: AbortSignal.timeout(5000) });
if (!resp.ok) throw new Error(`Metadata endpoint returned HTTP ${resp.status}`);

Type guard

null

Try / catch

try {
  await signIn(envName);
} catch (err) {
  if ((err as Error).message.includes('Failed to load OAuth metadata')) {
    console.error('Check the environment baseUrl and that the server is running:', (err as Error).message);
  } else throw err;
}

Prevention

Validate the environment baseUrl (scheme, host, port) before storing it
Confirm the server exposes the OAuth discovery endpoint (curl the well-known URL)
Account for proxies/VPNs that block the metadata request
Keep server and CLI versions compatible

When it happens

Trigger: Signing in / initializing an environment whose baseUrl points at a server that does not respond: wrong port, server not started, DNS failure, TLS certificate problems, or requests timing out on every retry attempt.

Common situations: Typo in the environment's baseUrl (e.g. http vs https, wrong port); NocoBase backend not running or behind a reverse proxy that strips the OAuth metadata route; offline/VPN-required networks.

Related errors

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/b88775792a0d3e14. Report an issue: GitHub.