paperclipai/paperclip · error · Error

local_trusted mode requires loopback host binding (received:

Error message

local_trusted mode requires loopback host binding (received: ${config.host}). Use authenticated mode for non-loopback deployments.

What it means

Startup safety check in startServer: deploymentMode is local_trusted (no authentication) but config.host binds a non-loopback interface (e.g. 0.0.0.0 or a LAN IP). An unauthenticated local_trusted server on a public interface would expose full-control board access, so startup aborts and instructs switching to authenticated mode.

Source

Thrown at server/src/index.ts:623

    }
  
    const embeddedAdminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
    const dbStatus = await ensurePostgresDatabase(embeddedAdminConnectionString, "paperclip");
    if (dbStatus === "created") {
      logger.info("Created embedded PostgreSQL database: paperclip");
    }
  
    const embeddedConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
    const shouldAutoApplyFirstRunMigrations = !clusterAlreadyInitialized || dbStatus === "created";
    if (shouldAutoApplyFirstRunMigrations) {
      logger.info("Detected first-run embedded PostgreSQL setup; applying pending migrations automatically");
    }
    migrationSummary = await ensureMigrations(embeddedConnectionString, "Embedded PostgreSQL", {
      autoApply: shouldAutoApplyFirstRunMigrations,
    });
  
    db = createDb(embeddedConnectionString);
    pluginMigrationDb = db;
    logger.info("Embedded PostgreSQL ready");
    activeDatabaseConnectionString = embeddedConnectionString;
    resolvedEmbeddedPostgresPort = port;
    startupDbInfo = { mode: "embedded-postgres", dataDir, port };
  }

  // Ends every pool this process opened. Used by the orderly shutdown path
  // (after the application services, before the embedded provider stops) and
  // 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.

View on GitHub (pinned to 01ad858492)

Solutions

1. Bind to a loopback host (127.0.0.1 or ::1) when using local_trusted mode.
2. Switch to authenticated mode for non-loopback deployments.

When it happens

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