Astro Dev Already Running: Use --ignore-lock for a Second Server

Decide whether you need a second server#

First inspect the existing process:

1
pnpm exec astro dev status

If the running server is yours and you only need to restart it, stop it through Astro’s lifecycle:

1
pnpm exec astro dev stop
2
pnpm exec astro dev

If a background server is stale, use the documented background lifecycle or --force path rather than creating an unmanaged copy. The Astro preview background guide covers the related preview commands; this article is about intentionally running multiple dev servers.

Use --ignore-lock when the first server must keep running. Typical reasons include comparing two configuration states, checking a different logging mode, or letting a short-lived tool inspect a second port without disturbing the main development session.

Use a different port explicitly#

Astro can choose another available port in some server-start scenarios, but an explicit port makes the two endpoints obvious:

1
# Main terminal
2
pnpm exec astro dev --port 4321
3

4
# Second terminal
5
pnpm exec astro dev --ignore-lock --port 4322

If port 4322 is already occupied, change it to a free port. --ignore-lock only skips Astro’s duplicate-project check; it does not override the operating system’s port binding rules.

When a script or browser automation checks the site, pass the second URL deliberately:

1
http://localhost:4322/

Do not assume that a successful process start means the browser is looking at the new instance. Verify the response and the server output from the same terminal that launched it.

Understand what the lock controls#

Astro’s dev lock records the running server’s information so commands such as astro dev status, astro dev stop, and astro dev logs can manage a background instance. The Astro CLI reference documents --ignore-lock as a way to start without checking or writing that lock.

The unmanaged second process therefore has an intentional limitation:

• astro dev status does not list it.
• astro dev stop does not stop it.
• astro dev logs does not provide its log lifecycle.
• --background and --force cannot be combined with --ignore-lock.

Keep the second process attached to its terminal when possible. Stop it with Ctrl+C, or terminate the exact process you started after confirming its PID. Do not remove the lock file to make the first process disappear; that can leave a live server unmanaged.

Do not use ignore-lock to hide a stale process#

If Astro reports that a server is already running but you did not start it, check the status output and the process owner before bypassing the lock:

1
pnpm exec astro dev status
2
ps -p <PID> -o pid=,ppid=,command=

Replace <PID> with the actual PID from the status output. If the process is dead but the lock is stale, use Astro’s normal stop or restart path first. Delete a lock file only as a last-resort cleanup after you have verified that no server from the project is alive; a lock file is state, not the server itself.

If an AI coding agent automatically starts Astro in background mode, the normal lock is part of the coordination contract. Use --ignore-lock only for the intentional second foreground server, not as a default flag in every script.

Keep the second build and route assumptions clear#

Both dev servers read the same source tree, but they can still differ in command-line flags, environment variables, and selected port. Write down what each instance is testing:

1
# Example: inspect a second configuration without changing the main process
2
ASTRO_LOG_LEVEL=debug pnpm exec astro dev \
3
  --ignore-lock \
4
  --port 4322

Avoid changing files under test while comparing two instances unless the difference is intentional. If a configuration change affects generated routes or assets, refresh both browser tabs and record which port produced each result.

This server-management boundary is separate from static URL output. If the issue is a generated pagination link that lacks .html, see Astro pagination URLs with .html instead of adding another dev server.

Verify and clean up#

Use a short checklist after starting the second server:

1. Confirm the first and second commands use different ports.
2. Request each URL and verify the expected project state.
3. Check the terminal output to identify which process served a response.
4. Stop the unmanaged second process with Ctrl+C.
5. Use astro dev status to confirm the managed server is still the one you expect.

The practical rule is to treat --ignore-lock as a scoped escape hatch. It is useful for a deliberate second foreground server, but it also opts that process out of Astro’s lifecycle management.

FAQ#