paperclipai/paperclip · error · Error

authenticated public exposure requires auth.baseUrlMode=expl

Error message

authenticated public exposure requires auth.baseUrlMode=explicit

What it means

Config consistency check in startServer (authenticated mode branch): deploymentExposure is 'public' but auth.baseUrlMode is not 'explicit'. Public authenticated deployments must pin an explicit auth base URL (see the companion check requiring auth.publicBaseUrl), so any other baseUrlMode is rejected at boot.

Source

Thrown at server/src/index.ts:654

  };
  startupDatabase.close = closeDatabaseClients;
  
  // A claimed warm-pool stack may restart while its provider environment still
  // names the pool host. Restore the signed, durable identity before Better
  // Auth, routes, or child-runtime configuration capture any public URL.
  const restoredCloudRuntimeIdentity = await initializeCloudRuntimeIdentity(db as any);
  if (restoredCloudRuntimeIdentity) config = loadConfig();

  if (config.deploymentMode === "local_trusted" && !isLoopbackHost(config.host)) {
    throw new Error(
      `local_trusted mode requires loopback host binding (received: ${config.host}). ` +
        "Use authenticated mode for non-loopback deployments.",
    );
  }
  
  if (config.deploymentMode === "local_trusted" && config.deploymentExposure !== "private") {
    throw new Error("local_trusted mode only supports private exposure");
  }
  
  if (config.deploymentMode === "authenticated") {
    if (config.authBaseUrlMode === "explicit" && !config.authPublicBaseUrl) {
      throw new Error("auth.baseUrlMode=explicit requires auth.publicBaseUrl");
    }
    if (config.deploymentExposure === "public") {
      if (config.authBaseUrlMode !== "explicit") {
        throw new Error("authenticated public exposure requires auth.baseUrlMode=explicit");
      }
      if (!config.authPublicBaseUrl) {
        throw new Error("authenticated public exposure requires auth.publicBaseUrl");
      }
    }
  }

  const requestedListenPort = config.port;
  const listenPort = await detectPort({
    port: requestedListenPort,

View on GitHub (pinned to 01ad858492)

Solutions

1. Set auth.baseUrlMode=explicit for authenticated public exposure.
2. Use private exposure or local_trusted mode instead.

When it happens

Trigger: Thrown at server/src/index.ts:535 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/dd5b761b6ef119ca. Report an issue: GitHub.