withastro/astro · error · Error

`--force` and `--ignore-lock` cannot be used together. `--f

Error message

`--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.

What it means

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." thrown in withastro/astro.

Source

Thrown at packages/astro/src/cli/preview/index.ts:80

	if (subcommand === 'stop') {
		await stop({ flags, logger, config: previewServerCommand });
		return;
	}

	if (subcommand === 'status') {
		await status({ flags, logger, config: previewServerCommand });
		return;
	}

	if (subcommand === 'logs') {
		await logs({ flags, logger, config: previewServerCommand });
		return;
	}

	// 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.',

View on GitHub (pinned to e294953aa8)

When it happens

Trigger: Thrown at packages/astro/src/cli/preview/index.ts:80 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/2ab6b22a40b2391d. Report an issue: GitHub.