withastro/astro · error · Error
`--ignore-lock` cannot be used together with ${reason}. Bac
Error message
`--ignore-lock` cannot be used together with ${reason}.
Background preview servers rely on the lock file so `astro preview stop`, `astro preview status`, and `astro preview logs` can find them.
Run the preview server in the foreground to use --ignore-lock. What it means
Error "`--ignore-lock` cannot be used together with ${reason}. Background preview servers rely on the lock file so `astro preview stop`, `astro preview status`, and `astro preview logs` can find them. Run the preview server in the foreground to use --ignore-lock." thrown in withastro/astro.
Source
Thrown at packages/astro/src/cli/preview/index.ts:94
// Reject conflicting flag combinations up front, before starting anything.
if (ignoreLock) {
if (flags.force) {
throw new Error(
[
'`--force` and `--ignore-lock` cannot be used together.',
'',
'`--force` replaces the existing preview server; `--ignore-lock` starts a new one alongside it without touching the lock file. Choose one.',
].join('\n'),
);
}
}
if (ignoreLock && wantsBackground) {
const reason = flags.background
? '`--background`'
: 'an auto-detected AI agent environment, which runs the preview server in the background automatically';
throw new Error(
[
`\`--ignore-lock\` cannot be used together with ${reason}.`,
'',
'Background preview servers rely on the lock file so `astro preview stop`, `astro preview status`, and `astro preview logs` can find them.',
'Run the preview server in the foreground to use --ignore-lock.',
].join('\n'),
);
}
if (wantsBackground) {
await background({ flags, logger, config: previewServerCommand });
return;
}
if (subcommand) {
logger.error(
'SKIP_FORMAT',
`Unknown command: astro preview ${subcommand}\n\nRun \`astro preview --help\` to see available commands.`,View on GitHub (pinned to e294953aa8)
When it happens
Trigger: Thrown at packages/astro/src/cli/preview/index.ts:94 when the library encounters an invalid state.
Common situations: See trigger scenarios.
AI-assisted analysis of withastro/astro@e294953aa8 (2026-09-09).
Data as JSON: /api/errors/0ac146a0e5df71d3.
Report an issue: GitHub.