Astro dev server default port: 4321
Astro dev server uses TCP port 4321 by default. Astro tries the next available port when the one you gave is already in use, so the server may not be on 4321. Astro 7 also refuses a second astro dev in the same project: it records the running server’s URL, port and PID in .astro/dev.json, and the error points to astro dev stop. --ignore-lock, added in Astro 7.1.0, starts another server anyway, for example astro dev --ignore-lock --port 4322.
Key facts
| Port | Protocol | Role | Category |
|---|---|---|---|
| 4321 | TCP | astro dev and astro preview | Frontend |
What happens when the port is busy
Astro tries the next available port when the one you gave is already in use, so the server may not be on 4321. Astro 7 also refuses a second astro dev in the same project: it records the running server’s URL, port and PID in .astro/dev.json, and the error points to astro dev stop. --ignore-lock, added in Astro 7.1.0, starts another server anyway, for example astro dev --ignore-lock --port 4322.
Change the port
astro dev --port 4400Through a package.json script, pass the flag after the double dash: npm run dev -- --port 8080.
import { defineConfig } from 'astro/config';
export default defineConfig({
server: { port: 4400 },
});server.port defaults to 4321 and applies to both astro dev and astro preview.
import { defineConfig } from 'astro/config';
export default defineConfig({
server: ({ command }) => ({
port: command === 'dev' ? 4321 : 4000,
}),
});server can be a function of the command, so dev and preview can listen on different ports.
astro dev --ignore-lock --port 4322Starts a second server without checking or writing the lock file, so astro dev stop, status and logs do not track it. The flag was added in Astro 7.1.0.
Bind address
server.host defaults to false, which keeps the dev server off the network. Set it to true, or pass --host, to listen on all addresses, including LAN and public ones. --host with an address, such as 192.168.0.1, exposes it on that address.
What else uses this port
No other tool in this dataset uses port 4321 as a default.
The dataset is the 12 tools on the ports index.
Find and free this port
These commands find the process that holds TCP port 4321 and stop it. They come from the Port in use command generator. PID_NUMBER stands for the process ID you read from the first command: replace it before you run the others.
lsof -nP -iTCP:4321 -sTCP:LISTEN
ps -p PID_NUMBER -o pid,ppid,user,command
kill -TERM PID_NUMBERss -ltnp 'sport = :4321'
ps -p PID_NUMBER -o pid,ppid,user,command
kill -TERM PID_NUMBERGet-NetTCPConnection -LocalPort 4321 -State Listen -ErrorAction SilentlyContinue | Select-Object LocalAddress, LocalPort, State, OwningProcess
Get-CimInstance -ClassName Win32_Process -Filter "ProcessId = PID_NUMBER" | Select-Object ProcessId, ParentProcessId, Name, CommandLine
Stop-Process -Id PID_NUMBERRead the output of the second command before you stop anything, because the owner may be a container or another person’s process. Then run the first command again to confirm the port is free.
Next free ports
Counting up from 4321, the next three ports that no tool in this dataset uses as a default are 4322, 4323, and 4324. They are suggestions only: another program on your machine may hold any of them, so run the find command above before you choose one.
In Rig
Rig starts Astro with --port N, where N is the project’s port. If something else holds N, start_project returns a portConflict that names the owner and a suggested free port, unless you pass resolve_port=kill (stop the owner) or resolve_port=suggest (switch the project to a free port).
Collisions in practice
4321 is a deliberate outlier: Astro moved off 3000 in v3, so older Astro guides, READMEs and test scripts that still say localhost:3000 now point at whatever else owns that port, such as a Next.js or Nuxt app. Astro itself avoids a hard failure by stepping to the next free port, which is also the risk: a test run or an OAuth redirect can reach the wrong server without an error. Give each project its own server.port, and treat any hard-coded 3000 in an Astro repo as left over from before v3.
Frequently asked questions
Why does Astro use port 4321 and not 3000?
Astro v2.x ran the dev server on port 3000 by default. Astro v3.0 changed the default to 4321, which is why older tutorials and test configs still mention localhost:3000. Search your repo for hard-coded references, or set server.port to 3000 if you want the old address back.
Can I run two Astro dev servers from one project?
Astro 7 and later refuse a second astro dev in the same project because of the lock file at .astro/dev.json. Pass --ignore-lock with a different --port, for example astro dev --ignore-lock --port 4322. The flag was added in Astro 7.1.0.
Is the Astro dev server visible on my network?
No. server.host defaults to false, which keeps it off the network. Pass --host to listen on all addresses, or --host with a specific address to expose it on that one. Do that only on a network you trust.
Sources
Busy ports in Rig
When a start fails because a port is taken, Rig shows which process owns it when it can, and lets you reclaim the port or choose another. You do not need Rig to use this page.