paperclipai/paperclip · error · Error

test-drive requires its isolated embedded database. Remove D

Error message

test-drive requires its isolated embedded database. Remove DATABASE_URL and DATABASE_MIGRATION_URL from the selected data directory's .env, or choose a fresh --data-dir.

What it means

During a warm transition recovery, the transport re-registers the runner with the control plane and verifies the OLD registered connection. If the previously registered connection is not in `connect` mode with a string `connectUrl`, the transport cannot guarantee endpoint continuity for the warm transition and throws this error.

Source

Thrown at cli/src/commands/test-drive.ts:208

  process.env.PAPERCLIP_IN_WORKTREE = linkedWorktree ? "true" : "false";
  process.env.PAPERCLIP_OPEN_ON_LISTEN = "false";
  process.env.PAPERCLIP_DISABLE_CWD_ENV_FILE = "true";
  process.env.PAPERCLIP_DEPLOYMENT_MODE = "local_trusted";
  process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "private";
  process.env.PAPERCLIP_BIND = "loopback";
  process.env.HOST = "127.0.0.1";
  process.env.PORT = String(await resolveTestDriveServerPort());

  return { dataDir, linkedWorktree };
}

export function assertTestDriveDatabaseIsolation(
  configPath?: string,
  env: NodeJS.ProcessEnv = process.env,
  readConfigFile: (path?: string) => PaperclipConfig | null = readConfig,
): void {
  if (env.DATABASE_URL?.trim() || env.DATABASE_MIGRATION_URL?.trim()) {
    throw new Error(
      "test-drive requires its isolated embedded database. Remove DATABASE_URL and " +
        "DATABASE_MIGRATION_URL from the selected data directory's .env, or choose a fresh --data-dir.",
    );
  }

  const config = readConfigFile(configPath);
  if (config?.database.mode === "postgres") {
    throw new Error(
      "test-drive cannot reuse a data directory configured for an external PostgreSQL database. " +
        "Choose a fresh data directory or change database.mode to embedded-postgres.",
    );
  }
}

export function resolveTestDriveBootstrap(
  options: TestDriveOptions,
  env: NodeJS.ProcessEnv = process.env,
): ResolvedTestDriveBootstrap {

View on GitHub (pinned to 01ad858492)

Solutions

Ensure the runner was originally registered in `connect` mode with a valid string `connectUrl` before attempting warm transition recovery.
Re-register the runner with the control plane using a proper connect-mode endpoint, then retry the warm transition.
Fall back to a cold restart of the runner if endpoint continuity cannot be established.

Example fix

// before
// registration record with wrong mode
{ mode: "listen", port: 9100 }
// after
{ mode: "connect", connectUrl: "http://127.0.0.1:9100" }

Defensive patterns

Strategy: validation

Validate before calling

function isValidConnectConnection(c: unknown): c is { mode: "connect"; connectUrl: string } {
  return typeof c === "object" && c !== null && (c as any).mode === "connect" && typeof (c as any).connectUrl === "string";
}
if (!isValidConnectConnection(oldRegistration.connection)) throw new Error("endpoint must be connect-mode with string url");

Type guard

function isConnectMode(v: unknown): v is { mode: "connect"; connectUrl: string } {
  return !!v && typeof v === "object" && (v as any).mode === "connect" && typeof (v as any).connectUrl === "string";
}

Try / catch

try {
  await transport.startTurn(input);
} catch (e) {
  if (e.message === "native_runner_warm_transition_registered_endpoint_mismatch") {
    await reRegisterRunnerConnectMode(root); // cold re-register then retry
  }
}

Prevention

Always register runners in connect mode with a normalized string URL.
Validate registration records after control-plane migrations.
Avoid hand-editing runner registration records.

When it happens

Trigger: The old transition registration's connection (`oldConnection`) is not `{ mode: "connect", connectUrl: <string> }` — e.g. it was registered as a listen/spawn-mode connection or the connectUrl is missing/non-string.

Common situations: Control plane records a legacy or different connection mode for the runner; manual edits or migrations of runner registration records; a previous registration path that did not normalize the endpoint to connect mode.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/6258b3dc3fa12f9b. Report an issue: GitHub.