gotchajavascriptastroMajor
Astro dev server silently bumps port when occupied — use Vite strictPort
Viewed 0 times
strict portport conflictsilent port bumporphan processstale dev server
macosnodejsterminal
Error Messages
Problem
Astro dev server silently moves to the next available port (4322, 4323...) when the default port 4321 is occupied by a stale process. No error is shown. Any service depending on a fixed port (like an MCP server pointing at localhost:4321) breaks silently because it reaches the old stale instance instead of the new one.
Solution
Add strictPort to the Vite config in astro.config.mjs: vite: { server: { strictPort: true } }. This makes Astro fail with an error instead of silently bumping. Also fix orphan cleanup: use pkill -f to kill stale astro dev processes, and use /usr/sbin/lsof (full path) in startup scripts since PATH may be limited.
Why
Astro delegates to Vite for the dev server. Vite defaults to incrementing the port when EADDRINUSE occurs. The strictPort option makes it throw instead. Failing loud on port conflict is always better than silently serving on the wrong port.
Gotchas
- lsof may not be on PATH in non-interactive shells — use /usr/sbin/lsof
- Orphan node processes from crashed astro dev sessions hold ports indefinitely
- MCP servers with hardcoded URLs will silently hit stale instances on the expected port
Revisions (0)
No revisions yet.