paperclipai/paperclip · error · Error

authenticated public exposure requires auth.publicBaseUrl

Error message

authenticated public exposure requires auth.publicBaseUrl

What it means

Config consistency check in startServer (authenticated mode branch): deploymentExposure is 'public' and baseUrlMode is 'explicit', but auth.publicBaseUrl is still unset. The public deployment has no URL to anchor auth redirects, so startup aborts until PAPERCLIP_PUBLIC_URL / publicBaseUrl is configured.

Source

Thrown at server/src/index.ts:657

  // 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,
    hostname: config.host,
  });
  if (config.authBaseUrlMode === "explicit" && config.authPublicBaseUrl) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Set auth.publicBaseUrl to the public URL of the instance.
2. Change exposure or auth mode if a public base URL is not available.

When it happens

Trigger: Thrown at server/src/index.ts:538 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/87c66980372cff36. Report an issue: GitHub.