< _

Debugging Broken Local Dev Environments

Abstract generated cover for Debugging Broken Local Dev Environments.

Local development environments break in boring ways. That does not make them easy to fix. A project might work on one machine and fail on another. It might work before a pull and fail after. It might need a `.env` file, a virtual environment, Node packages, generated assets, a free port, or source images that were never committed. The trick is not to guess harder. The trick is to check the layers in order.

The Mental Model

A local dev environment has several layers: ```plain text Git state Environment variables Dependencies Generated assets Build command Running services Browser output Logs

When something fails, one of those layers is usually wrong.
Do not start by changing random code.
First find which layer is failing.
## Check Git State
Start with:
```bash
git status

This answers:

  • what branch am I on?
  • do I have local changes?
  • am I ahead or behind?
  • are there untracked files? If a pull fails because of local changes, do not blindly delete files. Decide whether the changes matter. If they do, commit them on a branch or stash them. If they are generated output, they may belong in `.gitignore`.

Check the README or Start Script

A project should have an obvious entry point. Examples:

./dev-start.sh
npm run dev
python manage.py runserver

If the start script exists, read what it does. It may create a virtual environment, install dependencies, sync content, build assets, and start a server. Understanding the script prevents bad assumptions. If the script fails, note which step failed. Do not treat the whole project as broken if only one optional sync step failed.

Check Environment Variables

Missing or malformed environment variables are common. Questions to ask:

  • does `.env` exist?
  • is it ignored by Git?
  • does `.env.example` document required values?
  • are secrets present locally but not committed?
  • does the script require config or skip optional features? A good error should say what variable is missing. If the error is vague, improve the validation. Configuration bugs are much easier to fix when scripts fail clearly.

Check Dependencies

Python projects may need:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Node projects may need:

npm install

Other projects may need Go modules, Docker images, or system packages. The important question is:

Are dependencies declared in the repo, or only installed globally on one machine? If the project only works because of hidden global state, it is not portable yet.

Check Ports

Local servers fail when ports are already in use. Common symptoms:

  • server exits immediately
  • browser loads an old app
  • script says address already in use Check what is listening:
lsof -nP -iTCP:3000 -sTCP:LISTEN

Then decide whether to stop that process or run the project on another port. Good dev scripts should print useful port conflict information.

Check Build Output

If the browser shows a missing page, check whether the site actually built. For a static site, ask:

  • does the output directory exist?
  • does it contain `index.html`?
  • did the build finish before the browser opened?
  • are source assets present?
  • are generated assets ignored or committed correctly? The browser error may be a symptom of a missing build step, not a routing problem.

Common Mistakes

Mistake 1: Debugging from the browser first

The browser shows the final symptom. The real problem may be Git, config, dependencies, ports, or build output.

Mistake 2: Copying local fixes without understanding them

If you fix one machine by editing generated files or local state, the next machine may still fail. Fix the source of the problem.

Mistake 3: Committing secrets or generated junk

Do not commit `.env` just because it makes the project work locally. Do not commit build output unless the project intentionally tracks it.

Where This Shows Up in Real Projects

This happens constantly when moving a project between machines. A site might work locally because content was already synced, images were already generated, or packages were already installed. A fresh clone exposes missing assumptions. That is a good test. If a fresh clone cannot run with documented setup and local secrets, the project still has portability problems.

Key Takeaways

  • Debug local setup by checking layers in order.
  • Start with `git status`.
  • Read the start script instead of guessing.
  • Validate environment variables clearly.
  • Make dependencies explicit.
  • Check ports and build output.

  • Fix source problems, not just one machine's local state.

    Related Articles

  • Git Stash Explained With Real Workflows

  • Environment Variables for Python and Django Projects
  • VPS Deployment Basics for Developers

← Back to Blog Index