paperclipai/paperclip · error · Error

auth.baseUrlMode=explicit requires auth.publicBaseUrl

Error message

auth.baseUrlMode=explicit requires auth.publicBaseUrl

What it means

Config consistency check in startServer (authenticated mode branch): auth.baseUrlMode is 'explicit' but auth.publicBaseUrl is unset. Explicit base-URL mode requires a concrete public base URL to build auth links/redirects, so the contradictory configuration is rejected at startup.

Source

Thrown at server/src/index.ts:650

  // by the fail-loud startup path, so no exit leaves pooled backends behind.
  const closeDatabaseClients = async () => {
    const clients = pluginMigrationDb === db ? [db] : [db, pluginMigrationDb];
    await Promise.all(clients.map((client) => endDatabaseClient(client, 5)));
  };
  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");
      }
    }
  }

View on GitHub (pinned to 01ad858492)

Solutions

1. Set auth.publicBaseUrl in the config when auth.baseUrlMode=explicit.
2. Use a different auth.baseUrlMode if the public base URL should be derived automatically.

When it happens

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

Common situations: See trigger scenarios.

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