{"record":{"id":"bef60b52ba0a896a","repo":"withastro/astro","slug":"another-astro-dev-server-is-already-running-ur","errorCode":null,"errorMessage":"Another astro dev server is already running.\n\n  URL:  ${existingServer.url}\n  PID:  ${existingServer.pid}\n\nRun `astro dev stop` to stop it, or use `astro dev --force` to replace it.","messagePattern":"Another astro dev server is already running\\.\n\n  URL:  (.+?)\n  PID:  (.+?)\n\nRun `astro dev stop` to stop it, or use `astro dev --force` to replace it\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/cli/dev/index.ts","lineNumber":221,"sourceCode":"\t\tconst inlineConfig = flagsToAstroInlineConfig(flags);\n\t\treturn await devServer(inlineConfig);\n\t}\n\n\tconst existingServer = checkExistingServer(root);\n\tif (existingServer) {\n\t\tif (flags.force) {\n\t\t\t// --force: kill the existing server and replace it\n\t\t\tawait killDevServer(root, existingServer);\n\t\t} else {\n\t\t\tconst message = [\n\t\t\t\t'Another astro dev server is already running.',\n\t\t\t\t'',\n\t\t\t\t`  URL:  ${existingServer.url}`,\n\t\t\t\t`  PID:  ${existingServer.pid}`,\n\t\t\t\t'',\n\t\t\t\t`Run \\`astro dev stop\\` to stop it, or use \\`astro dev --force\\` to replace it.`,\n\t\t\t].join('\\n');\n\t\t\tthrow new Error(message);\n\t\t}\n\t}\n\n\tconst inlineConfig = flagsToAstroInlineConfig(flags);\n\tconst server = await devServer(inlineConfig);\n\n\t// Use Vite's resolved URL which accounts for host and protocol (http/https).\n\tconst serverUrl = resolveLockFileUrl(server.resolvedUrls);\n\tif (serverUrl) {\n\t\twriteLockFile(root, {\n\t\t\tpid: process.pid,\n\t\t\tport: server.address.port,\n\t\t\turl: serverUrl,\n\t\t\turls: server.resolvedUrls,\n\t\t\tbackground: !!process.env.ASTRO_DEV_BACKGROUND,\n\t\t\tstartedAt: new Date().toISOString(),\n\t\t});\n","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/cli/dev/index.ts#L203-L239","documentation":"Astro writes a lock file (containing PID, port, URL) to the project root's `.astro` directory when `astro dev` starts. On the next `astro dev` invocation it reads that file, checks whether the recorded PID is still alive, and refuses to start a second dev server against the same root. This prevents port/PID conflicts and ensures only one HMR process owns a project at a time.","triggerScenarios":"Running `astro dev` when `checkExistingServer(root, 'dev')` returns a non-null result (a live process holding the lock for that root). The `--force` flag bypasses this by calling `killDevServer` first.","commonSituations":"A previous `astro dev` was left running in another terminal or editor; a crashed session left a stale-but-live process; CI reused a workspace without tearing down the prior server; you switched branches but forgot the old server is still bound to the project root.","solutions":["Run `astro dev stop` to stop the existing server (uses the PID from the lock file).","Run `astro dev --force` to kill the existing server and replace it in one step.","If the PID is stale but the process appears gone, manually kill the process holding the port and delete the lock file in `.astro/`.","Check `ps -p <PID>` to confirm whether the recorded PID is actually a live Astro process before killing."],"exampleFix":"// before\n$ astro dev\n// after\n$ astro dev stop && astro dev\n// or\n$ astro dev --force","handlingStrategy":"validation","validationCode":"import { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nfunction isDevServerRunning(root) {\n  const lockPath = join(root, '.astro', 'dev.lock');\n  if (!existsSync(lockPath)) return null;\n  try {\n    const { pid, url } = JSON.parse(readFileSync(lockPath, 'utf-8'));\n    if (pid && process.kill(pid, 0)) return { pid, url };\n  } catch {}\n  return null;\n}\n\nconst existing = isDevServerRunning(process.cwd());\nif (existing) console.log(`Already running at ${existing.url} (PID ${existing.pid}) — pass --force.`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always stop dev servers with `astro dev stop` before starting a new one.","Use `astro dev --force` in scripts that may reuse a workspace.","Add `astro dev stop` to your editor/CI teardown steps."],"tags":["cli","dev-server","lock-file","concurrency"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}