{"record":{"id":"fa6880169d9801d6","repo":"withastro/astro","slug":"ignore-lock-cannot-be-used-together-with-rea","errorCode":null,"errorMessage":"`--ignore-lock` cannot be used together with ${reason}.\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 (.+?)\\.\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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/cli/dev/index.ts#L146-L182","documentation":"`astro dev` validates flag combinations before starting anything. `--ignore-lock` skips the `.astro/dev.json` lock file, but background dev servers (explicit `--background`, or auto-enabled when an AI coding agent environment is detected) rely on that lock file for `astro dev stop`, `astro dev status`, and `astro dev logs`; `--force` likewise needs the lock file to replace the existing server. Combining `--ignore-lock` with either is rejected up front by getBackgroundIgnoreLockConflict / getForceIgnoreLockConflict.","triggerScenarios":"`astro dev --ignore-lock --background`; `astro dev --ignore-lock --force`; or plain `astro dev --ignore-lock` run inside a detected AI-agent environment, which implies background mode and produces the 'auto-detected AI agent environment' reason string.","commonSituations":"Scripts or coding agents using `--ignore-lock` to dodge a stale-lock error while agent detection silently enables background mode; muscle-memory flag stacking (`--force --ignore-lock`) that expresses contradictory intent.","solutions":["Drop `--ignore-lock` and deal with the existing server properly: `astro dev stop` or `astro dev --force`","To keep `--ignore-lock`, run in the foreground and outside an agent-detected environment (no `--background`)","If a stale lock is the underlying problem, use `astro dev --force` or delete `.astro/dev.json` in the project root"],"exampleFix":"# before\nastro dev --ignore-lock --background   # rejected before start\n\n# after\nastro dev stop      # or: astro dev --force\nastro dev","handlingStrategy":"validation","validationCode":"// validate flags before spawning `astro dev`\nfunction devFlagsAreConsistent(flags, agentEnvDetected) {\n  const wantsBackground = flags.background === true || agentEnvDetected;\n  if (flags.ignoreLock === true && (wantsBackground || flags.force === true)) {\n    return false; // will be rejected by astro dev\n  }\n  return true;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat `--ignore-lock` as a foreground-only escape hatch; never combine it with `--background` or `--force`","In agent/CI environments, check whether background mode will be auto-enabled before adding lock-related flags","Prefer `astro dev stop` / `astro dev --force` over `--ignore-lock` when a lock file is in the way"],"tags":["cli","astro-dev","flags","lock-file","background-server"],"backgroundTag":"invalid-cli-flag-combination","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}