withastro/astro · error · Error

`--ignore-lock` cannot be used together with `--background`.

Error message

`--ignore-lock` cannot be used together with `--background`.

Background dev servers rely on the lock file so `astro dev stop`, `astro dev status`, and `astro dev logs` can find them.
Run the dev server in the foreground to use --ignore-lock.

What it means

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

Source

Thrown at packages/astro/src/cli/dev/index.ts:164

	if (subcommand === 'status') {
		const { status } = await import('./status.js');
		await status({ flags, logger });
		return;
	}

	// Handle `astro dev logs`
	if (subcommand === 'logs') {
		const { logs } = await import('./logs.js');
		await logs({ flags, logger });
		return;
	}

	// Reject conflicting flag combinations up front, before starting anything.
	if (ignoreLock) {
		const conflict =
			getBackgroundIgnoreLockConflict(flags, wantsBackground) ?? getForceIgnoreLockConflict(flags);
		if (conflict) {
			throw new Error(conflict);
		}
	}

	// Handle `astro dev --background` or auto-enable when an AI coding agent is detected.
	// Skip if ASTRO_DEV_BACKGROUND is set — this means we're the spawned child process
	// and should run the foreground dev server, not recurse into background mode.
	if (wantsBackground) {
		const { background } = await import('./background.js');
		await background({ flags, logger });
		return;
	}

	// Unknown subcommand — exit with an error before starting the server.
	if (subcommand) {
		logger.error(
			'SKIP_FORMAT',
			`Unknown command: astro dev ${subcommand}\n\nRun \`astro dev --help\` to see available commands.`,
		);

View on GitHub (pinned to d081033d5f)

Solutions

1. Drop --ignore-lock when you want background mode (let the agent/CLI manage the lock file).
2. Or run in the foreground (unset --background and disable agent auto-detection via env) to keep --ignore-lock.
3. For the --force + --ignore-lock case, choose one: --force to replace, or --ignore-lock to run alongside.
4. If an agent is auto-enabling background, set ASTRO_DEV_BACKGROUND or stop the agent's background invocation before using --ignore-lock.

Example fix

# before
astro dev --background --ignore-lock

# after — choose one
astro dev --background            # tracked background server
astro dev --ignore-lock           # untracked, foreground only

function validateDevFlags(flags: { background?: boolean; ignoreLock?: boolean; force?: boolean }): string | null {
  if (flags.ignoreLock && flags.background) return 'cannot combine --ignore-lock with --background';
  if (flags.ignoreLock && flags.force) return 'cannot combine --ignore-lock with --force';
  return null;
}

function hasIgnoreLockConflict(f: Record<string, unknown>): boolean {
  return Boolean(f['ignoreLock']) && (Boolean(f['background']) || Boolean(f['force']));
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown error parsing tsconfig.json or jsconfig.json. Could
• Another astro dev server is already running. URL: ${exis
• ConfigNotFound
• CannotOptimizeSvg
• RemoteImageNotAllowed

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/b85f9d381ca729b3. Report an issue: GitHub.