paperclipai/paperclip · error · Error

authenticated public deployments require DATABASE_URL or con

Error message

authenticated public deployments require DATABASE_URL or config.database.connectionString; refusing embedded PostgreSQL fallback

What it means

Deployment contract guard in assertCloudDatabaseContract: the server runs in authenticated mode with public exposure, but no DATABASE_URL / config.database.connectionString is configured. Refusing to fall back to embedded PostgreSQL, since an internet-exposed authenticated deployment must not run on an unsecured embedded database.

Source

Thrown at server/src/index.ts:321

      throw migrationRefusalError(
        state,
        `${label} has pending migrations (${formatPendingMigrationSummary(state.pendingMigrations)}). ` +
          "Refusing to start against a stale schema. Run pnpm db:migrate or set PAPERCLIP_MIGRATION_AUTO_APPLY=true.",
      );
    }

    logger.info({ pendingMigrations: state.pendingMigrations }, `Applying ${state.pendingMigrations.length} pending migrations for ${label}`);
    await applyPendingMigrations(connectionString);
    return "applied (pending migrations)";
  }
  
  function isPostgresConnectionString(connectionString: string): boolean {
    try {
      const parsed = new URL(connectionString);
      return parsed.protocol === "postgres:" || parsed.protocol === "postgresql:";
    } catch {
      return false;
    }
  }

  function assertCloudDatabaseContract(): void {
    if (config.deploymentMode !== "authenticated" || config.deploymentExposure !== "public") {
      return;
    }
    if (!config.databaseUrl) {
      // Under a managed-cloud supervisor a missing DATABASE_URL on boot
      // is the config-application race (the container can start before
      // the staged variables land), not operator error — the supervisor
      // restarts once the config holds. A malformed value below is a
      // real misconfiguration and stays an always-reported Error.
      throw new StartupRefusalError(
        "database-contract-unmet",
        "authenticated public deployments require DATABASE_URL or config.database.connectionString; refusing embedded PostgreSQL fallback",
      );
    }
    if (!isPostgresConnectionString(config.databaseUrl)) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Set DATABASE_URL (or config.database.connectionString) to an external Postgres database for authenticated public deployments.
2. Use a non-public exposure mode if you want the embedded PostgreSQL fallback.

When it happens

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