Localhost not working? Here's the fix.

Match your error message

The step-by-step checklist

1. 1. Is the server actually still running?

   Go back to the terminal window where you started it. If it crashed, you'll see an error near the bottom, or the prompt will just be sitting there waiting for a new command instead of showing "listening" or "ready." A closed terminal, a computer that went to sleep, or a stopped Docker container will all silently kill your localhost server.

   Fix: restart it (e.g. npm run dev, python manage.py runserver, docker start my-app) and watch for the exact URL and port it prints.

2. 2. Are you using the right port?

   The number after the colon in localhost:3000 matters as much as the word "localhost" itself. Different tools default to different ports — React/Vite often use 5173 or 3000, Django uses 8000, a database might be on 5432 or 27017. Loading the wrong port looks identical to a broken server.

   Fix: re-read your terminal's startup output for the exact address it printed, and use that one, every time.

3. 3. Is something else already using that port?

   Two programs can't listen on the same port at once. If you started a second copy of your app, or another project happens to use the same default port, the new one usually fails to start (or silently fails to bind) — while an old, stale copy keeps answering instead.

   # Mac / Linux — find what's using port 3000
   lsof -i :3000
   
   # then stop it
   kill -9 <PID>
   
   # Windows (PowerShell) — find it
   netstat -ano | findstr :3000
   
   # then stop it
   taskkill /PID <PID> /F

4. 4. Check for a firewall, VPN, or antivirus interfering

   Some corporate VPNs and security tools intercept or block local ports, especially ones under active development. If localhost worked yesterday and nothing in your code changed, a background update to security software is a common, invisible culprit.

   Fix: temporarily disconnect the VPN or pause the security tool and reload the page to confirm, then allow that specific port through it.

5. 5. Double-check http vs. https, and for typos

   Most local dev servers are plain http://, not https://. Browsers sometimes auto-upgrade a bookmarked or auto-completed URL to https, which then fails because your local server isn't listening for encrypted traffic. Also watch for an extra character, a missing colon, or a leftover path from a previous project.

6. 6. Docker: check the port mapping, not just the container status

   docker ps showing "Up" doesn't guarantee localhost can reach it — the port mapping has to be explicit.

   # Wrong: no port exposed to your machine
   docker run my-app
   
   # Right: maps container's port 80 to your machine's localhost:8080
   docker run -p 8080:80 my-app

   Also make sure the app inside the container binds to 0.0.0.0, not 127.0.0.1 — binding to 127.0.0.1 inside a container makes it unreachable from outside that container, even with the right -p mapping.

7. 7. Trying to open it from another device? That's expected to fail.

   localhost always refers to the device making the request. Your phone's localhost has nothing running on it, so it will never show your laptop's project — no matter how correct the port is.

   Fix (same Wi-Fi only): find your computer's local network IP and use that instead.

   # Mac
   ipconfig getifaddr en0
   
   # Windows
   ipconfig
   
   # Linux
   hostname -I

   Then visit something like http://192.168.1.23:3000 from your phone. Note this only works on the same local network — it still won't work from a different Wi-Fi, from cellular data, or for anyone outside your house or office. For that, you need the cloud.

8. 8. A modified hosts file redirecting "localhost" elsewhere

   Rare, but real — especially if some other tool (or an ad-blocker, or a well-meaning tutorial) previously edited your system's hosts file. This file can override what "localhost" even resolves to.

   # Mac / Linux
   cat /etc/hosts
   
   # Windows
   type C:\Windows\System32\drivers\etc\hosts

   Look for a line containing localhost that isn't simply 127.0.0.1 localhost, and fix or remove it (you'll likely need administrator/sudo access).

9. 9. Clear the browser's cache for that page

   Browsers aggressively cache redirects and service workers, which can keep showing an old failure (or an old version of your app) even after the real problem is fixed. Try a hard refresh, an incognito/private window, or a different browser entirely to rule this out.

10. 10. If nothing above helps: stop relying on localhost at all

    If your goal was ever to share this with someone else, have it survive a reboot, or use it from more than one device or network, localhost was the wrong long-term home for it from the start — not because you did something wrong, but because that's simply not what a loopback address is for.

    The durable fix is to put the project on a server that's always on and has a public address: the cloud. See exactly how, straight from your terminal, on the deploy guide.