{"record":{"id":"b85f9d381ca729b3","repo":"withastro/astro","slug":"ignore-lock-cannot-be-used-together-with-ba","errorCode":null,"errorMessage":"`--ignore-lock` cannot be used together with `--background`.\n\nBackground dev servers rely on the lock file so `astro dev stop`, `astro dev status`, and `astro dev logs` can find them.\nRun the dev server in the foreground to use --ignore-lock.","messagePattern":"`--ignore-lock` cannot be used together with `--background`\\.\n\nBackground dev servers rely on the lock file so `astro dev stop`, `astro dev status`, and `astro dev logs` can find them\\.\nRun the dev server in the foreground to use --ignore-lock\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/cli/dev/index.ts","lineNumber":164,"sourceCode":"\tif (subcommand === 'status') {\n\t\tconst { status } = await import('./status.js');\n\t\tawait status({ flags, logger });\n\t\treturn;\n\t}\n\n\t// Handle `astro dev logs`\n\tif (subcommand === 'logs') {\n\t\tconst { logs } = await import('./logs.js');\n\t\tawait logs({ flags, logger });\n\t\treturn;\n\t}\n\n\t// Reject conflicting flag combinations up front, before starting anything.\n\tif (ignoreLock) {\n\t\tconst conflict =\n\t\t\tgetBackgroundIgnoreLockConflict(flags, wantsBackground) ?? getForceIgnoreLockConflict(flags);\n\t\tif (conflict) {\n\t\t\tthrow new Error(conflict);\n\t\t}\n\t}\n\n\t// Handle `astro dev --background` or auto-enable when an AI coding agent is detected.\n\t// Skip if ASTRO_DEV_BACKGROUND is set — this means we're the spawned child process\n\t// and should run the foreground dev server, not recurse into background mode.\n\tif (wantsBackground) {\n\t\tconst { background } = await import('./background.js');\n\t\tawait background({ flags, logger });\n\t\treturn;\n\t}\n\n\t// Unknown subcommand — exit with an error before starting the server.\n\tif (subcommand) {\n\t\tlogger.error(\n\t\t\t'SKIP_FORMAT',\n\t\t\t`Unknown command: astro dev ${subcommand}\\n\\nRun \\`astro dev --help\\` to see available commands.`,\n\t\t);","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/cli/dev/index.ts#L146-L182","documentation":"`astro dev` rejects the combination of `--ignore-lock` with `--background` (explicit or auto-enabled when an AI agent is detected). Background dev servers depend on the lock file so that `astro dev stop`, `status`, and `logs` can locate them; ignoring the lock would orphan the server. The conflict string is built by getBackgroundIgnoreLockConflict (or getForceIgnoreLockConflict for --force).","triggerScenarios":"Running `astro dev --background --ignore-lock`, or running `astro dev --ignore-lock` in an environment where isRunByAgent() is true (which auto-enables background). Also fires for `--force --ignore-lock` via getForceIgnoreLockConflict.","commonSituations":"An AI coding agent (detected automatically) running `astro dev --ignore-lock`; a user passing both flags manually; a wrapper script that always sets --ignore-lock while the agent auto-backgrounds; combining --force with --ignore-lock.","solutions":["Drop --ignore-lock when you want background mode (let the agent/CLI manage the lock file).","Or run in the foreground (unset --background and disable agent auto-detection via env) to keep --ignore-lock.","For the --force + --ignore-lock case, choose one: --force to replace, or --ignore-lock to run alongside.","If an agent is auto-enabling background, set ASTRO_DEV_BACKGROUND or stop the agent's background invocation before using --ignore-lock."],"exampleFix":"# before\nastro dev --background --ignore-lock\n\n# after — choose one\nastro dev --background            # tracked background server\nastro dev --ignore-lock           # untracked, foreground only","handlingStrategy":"validation","validationCode":"function validateDevFlags(flags: { background?: boolean; ignoreLock?: boolean; force?: boolean }): string | null {\n  if (flags.ignoreLock && flags.background) return 'cannot combine --ignore-lock with --background';\n  if (flags.ignoreLock && flags.force) return 'cannot combine --ignore-lock with --force';\n  return null;\n}","typeGuard":"function hasIgnoreLockConflict(f: Record<string, unknown>): boolean {\n  return Boolean(f['ignoreLock']) && (Boolean(f['background']) || Boolean(f['force']));\n}","tryCatchPattern":null,"preventionTips":["Do not pass --ignore-lock to background dev servers you want to manage later.","Let AI agent tooling manage the lock file instead of forcing --ignore-lock.","Choose --force OR --ignore-lock, never both."],"tags":["cli","dev-server","flags","configuration"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}