{"record":{"id":"98234d2f50872e0f","repo":"withastro/astro","slug":"another-astro-preview-server-is-already-running","errorCode":null,"errorMessage":"Another astro preview server is already running.\n\n  URL:  ${existingServer.url}\n  PID:  ${existingServer.pid}\n\nRun `astro preview stop` to stop it, or use `astro preview --force` to replace it.","messagePattern":"Another astro preview server is already running\\.\n\n  URL:  (.+?)\n  PID:  (.+?)\n\nRun `astro preview stop` to stop it, or use `astro preview --force` to replace it\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/cli/preview/index.ts","lineNumber":146,"sourceCode":"\t\t\t\t\t'This instance is not tracked by `astro preview stop`, `astro preview status`, or `astro preview logs`.',\n\t\t\t\t].join('\\n'),\n\t\t\t);\n\t\t}\n\t\tconst inlineConfig = flagsToAstroInlineConfig(flags);\n\t\treturn await previewServer(inlineConfig);\n\t}\n\n\tconst existingServer = await checkExistingServer(root, 'preview');\n\tif (existingServer) {\n\t\tconst message = [\n\t\t\t'Another astro preview server is already running.',\n\t\t\t'',\n\t\t\t`  URL:  ${existingServer.url}`,\n\t\t\t`  PID:  ${existingServer.pid}`,\n\t\t\t'',\n\t\t\t`Run \\`astro preview stop\\` to stop it, or use \\`astro preview --force\\` to replace it.`,\n\t\t].join('\\n');\n\t\tthrow new Error(message);\n\t}\n\n\tconst inlineConfig = flagsToAstroInlineConfig(flags);\n\tconst server = await previewServer(inlineConfig);\n\tconst serverUrl = server.urls?.local[0]\n\t\t? new URL(server.urls.local[0]).origin\n\t\t: `http://${server.host ?? 'localhost'}:${server.port}`;\n\n\twriteLockFile(\n\t\troot,\n\t\t{\n\t\t\tpid: process.pid,\n\t\t\tport: server.port,\n\t\t\turl: serverUrl,\n\t\t\turls: server.urls,\n\t\t\tbackground: !!process.env.ASTRO_PREVIEW_BACKGROUND,\n\t\t\tstartedAt: new Date().toISOString(),\n\t\t},","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/cli/preview/index.ts#L128-L164","documentation":"`astro preview` reads the preview lock file (`.astro/preview.json` under the project root) and probes the recorded PID before starting. A live preview server is already registered for this root, so the command aborts instead of orphaning `astro preview stop`.","triggerScenarios":"Running `astro preview` (typically after `astro build`) while another preview server for the same project root is still running — a previous terminal, a detached process, or tooling that started preview earlier.","commonSituations":"Iterating on production builds and forgetting the previous preview; CI or scripts running preview twice; editor task runners keeping preview alive.","solutions":["Run `astro preview stop` to stop the existing server, then run `astro preview` again","Or replace it: `astro preview --force`","If the recorded PID is dead (or was reused by an unrelated process), delete `.astro/preview.json` in the project root and retry"],"exampleFix":"# before\nastro preview   # Another astro preview server is already running. URL: ... PID: ...\n\n# after\nastro preview stop\nastro preview\n# or replace directly:\nastro preview --force","handlingStrategy":"validation","validationCode":"import { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nfunction previewServerIsRunning(root) {\n  const lock = join(root, '.astro', 'preview.json');\n  if (!existsSync(lock)) return false;\n  try {\n    const { pid } = JSON.parse(readFileSync(lock, 'utf8'));\n    process.kill(pid, 0);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nif (previewServerIsRunning(root)) {\n  // run `astro preview stop` (or pass --force) before `astro preview`\n}","typeGuard":null,"tryCatchPattern":"import { spawnSync } from 'node:child_process';\nconst r = spawnSync('astro', ['preview'], { encoding: 'utf8' });\nif (r.status !== 0 && /Another astro preview server is already running/.test(r.stderr)) {\n  spawnSync('astro', ['preview', 'stop'], { stdio: 'inherit' });\n  // retry `astro preview` once\n}","preventionTips":["Stop preview servers with `astro preview stop` at the end of verification scripts","Use `astro preview --force` in automation where replacing a prior server is intended","Check `.astro/preview.json` in the project root when a start fails unexpectedly — a reused PID can masquerade as a live server"],"tags":["cli","astro-preview","lock-file","process-management"],"backgroundTag":"dev-server-already-running","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}