The 60-second check
Read the terminal URL
Run
npm run devand use the exact URL afterLocal:. Do not assume it is still 5173.Confirm that something is listening
# Windows PowerShell Get-NetTCPConnection -LocalPort 5173 -State Listen # macOS or Linux lsof -nP -iTCP:5173 -sTCP:LISTENTest without the browser
curl -I http://127.0.0.1:5173An HTTP response means the server is reachable. A refused connection means there is no listener at that address and port.
Match the symptom to the cause
| What you see | What it usually means | Next check |
|---|---|---|
ERR_CONNECTION_REFUSED | Vite stopped, started on a different port, or listens in a different network namespace. | Terminal output and the listener command above. |
| Vite opens on 5174 | 5173 was already occupied and Vite selected the next port. | Find the existing process or enable strictPort. |
ERR_BLOCKED_BY_CLIENT | A browser extension or privacy filter blocked the request. | Try a clean browser profile, then inspect DevTools. |
| Works inside WSL or a container only | The server is bound to loopback inside that environment, or the port was not published. | Bind deliberately and publish the container port. |
| HTML loads but API calls fail | The frontend is reachable; the failing request is a separate API, proxy, CORS, or environment-variable issue. | Inspect the failed request in DevTools, then paste its response headers into the CORS Header Analyzer. |
Make the port deterministic
Vite’s documented default is 5173, but it tries another port when that port is busy. Use strictPort when scripts, OAuth callbacks, or tests require one fixed origin.
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
server: {
port: 5173,
strictPort: true
}
})The CLI equivalent is:
npm run dev -- --port 5173 --strictPortPort conflict: stop the process already using 5173, or choose a different port. Do not kill a process until you have identified it.
WSL, Docker, and phone access
Vite binds to localhost by default. To accept connections from outside the current environment, bind it to all interfaces:
npm run dev -- --host 0.0.0.0
# Docker example
docker run --rm -p 5173:5173 your-imageThen open http://<computer-lan-ip>:5173 from the other device. In Docker, both the Vite host setting and -p 5173:5173 are required: one controls the listener; the other publishes the container port.
Security: 0.0.0.0 broadens who can reach the development server. Keep it behind a trusted local network and firewall, and do not expose a Vite dev server to the public internet.
The server responds, but it is the wrong page
- Check the process ID that owns 5173; another project may be running there.
- Check Vite’s configured
basewhen assets return 404 under a subpath. - Check the browser console for a failed module import instead of treating every blank screen as a network failure.
- If a reverse proxy is involved, test Vite directly first, then test the proxy route.
Official references
- Vite: Server optionsDefault port, strictPort, host, HTTPS, proxy, and allowed-host behavior.
- Docker: Publishing portsHow host-to-container port mapping works.
- MDN: Local network accessExplains loopback, local, and public address spaces.