{"record":{"id":"6258b3dc3fa12f9b","repo":"paperclipai/paperclip","slug":"test-drive-requires-its-isolated-embedded-database","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/test-drive.ts","lineNumber":208,"sourceCode":"  process.env.PAPERCLIP_IN_WORKTREE = linkedWorktree ? \"true\" : \"false\";\n  process.env.PAPERCLIP_OPEN_ON_LISTEN = \"false\";\n  process.env.PAPERCLIP_DISABLE_CWD_ENV_FILE = \"true\";\n  process.env.PAPERCLIP_DEPLOYMENT_MODE = \"local_trusted\";\n  process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE = \"private\";\n  process.env.PAPERCLIP_BIND = \"loopback\";\n  process.env.HOST = \"127.0.0.1\";\n  process.env.PORT = String(await resolveTestDriveServerPort());\n\n  return { dataDir, linkedWorktree };\n}\n\nexport function assertTestDriveDatabaseIsolation(\n  configPath?: string,\n  env: NodeJS.ProcessEnv = process.env,\n  readConfigFile: (path?: string) => PaperclipConfig | null = readConfig,\n): void {\n  if (env.DATABASE_URL?.trim() || env.DATABASE_MIGRATION_URL?.trim()) {\n    throw new Error(\n      \"test-drive requires its isolated embedded database. Remove DATABASE_URL and \" +\n        \"DATABASE_MIGRATION_URL from the selected data directory's .env, or choose a fresh --data-dir.\",\n    );\n  }\n\n  const config = readConfigFile(configPath);\n  if (config?.database.mode === \"postgres\") {\n    throw new Error(\n      \"test-drive cannot reuse a data directory configured for an external PostgreSQL database. \" +\n        \"Choose a fresh data directory or change database.mode to embedded-postgres.\",\n    );\n  }\n}\n\nexport function resolveTestDriveBootstrap(\n  options: TestDriveOptions,\n  env: NodeJS.ProcessEnv = process.env,\n): ResolvedTestDriveBootstrap {","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/cli/src/commands/test-drive.ts#L190-L226","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n// registration record with wrong mode\n{ mode: \"listen\", port: 9100 }\n// after\n{ mode: \"connect\", connectUrl: \"http://127.0.0.1:9100\" }","handlingStrategy":"validation","validationCode":"function isValidConnectConnection(c: unknown): c is { mode: \"connect\"; connectUrl: string } {\n  return typeof c === \"object\" && c !== null && (c as any).mode === \"connect\" && typeof (c as any).connectUrl === \"string\";\n}\nif (!isValidConnectConnection(oldRegistration.connection)) throw new Error(\"endpoint must be connect-mode with string url\");","typeGuard":"function isConnectMode(v: unknown): v is { mode: \"connect\"; connectUrl: string } {\n  return !!v && typeof v === \"object\" && (v as any).mode === \"connect\" && typeof (v as any).connectUrl === \"string\";\n}","tryCatchPattern":"try {\n  await transport.startTurn(input);\n} catch (e) {\n  if (e.message === \"native_runner_warm_transition_registered_endpoint_mismatch\") {\n    await reRegisterRunnerConnectMode(root); // cold re-register then retry\n  }\n}","preventionTips":["Always register runners in connect mode with a normalized string URL.","Validate registration records after control-plane migrations.","Avoid hand-editing runner registration records."],"tags":["runner","warm-transition","endpoint"],"backgroundTag":"unexpected-response-shape","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}