withastro/astro · error · Error

`--ignore-lock` cannot be used together with ${reason}. Bac

Error message

`--ignore-lock` cannot be used together with ${reason}.

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

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 52e6c34790)

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

Example fix

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

# after
astro dev stop      # or: astro dev --force
astro dev

Defensive patterns

Strategy: validation

Validate before calling

// validate flags before spawning `astro dev`
function devFlagsAreConsistent(flags, agentEnvDetected) {
  const wantsBackground = flags.background === true || agentEnvDetected;
  if (flags.ignoreLock === true && (wantsBackground || flags.force === true)) {
    return false; // will be rejected by astro dev
  }
  return true;
}

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/fa6880169d9801d6. Report an issue: GitHub.