App won't run locally? Check the environment before the code.

Use one diagnostic order

Randomly reinstalling packages, changing ports, and editing configuration destroys the state that could explain the failure. Keep each check narrow and record the result before taking the next action.

1. Reproduce the failure without changing anything

Start from the repository's documented command. Record the current directory, the command, the exit code, and the first causal error rather than the last line of a long stack trace. Confirm the project type from its own files: package.json, pyproject.toml, requirements.txt, go.mod, Dockerfile, or compose.yaml.

2. Match the runtime and dependency method to the repository

Check the installed runtime before installing anything. For Node, compare node --version with the repository's engines, version file, or documentation. For Python, compare python --version with requires-python and check whether the active interpreter belongs to the project's virtual environment.

Let the repository choose the package manager. npm documents that an existing lockfile drives dependency resolution; Python documents virtual environments as isolated, disposable environments that should be recreated rather than copied between machines. A missing dependency tree is evidence for installation. A dependency tree that exists but was created under another runtime is evidence for a controlled recreation.

Runtime: Node 24.x required / Node 22.x observed
Package manager: npm, package-lock.json present
Dependency state: node_modules missing
Supported next action: install with the repository's documented npm command
Unsupported shortcut: delete every lockfile and try another package manager

3. Compare environment-variable names without exposing values

Compare the names in .env.example or documented configuration against the names present in the local environment. Do not paste the file, print its values, or copy it into an issue. Node's current documentation defines .env files as key-value pairs consumed as environment variables; Docker Compose has its own interpolation and precedence behavior.

• Record missing required names such as DATABASE_URL or SESSION_SECRET.
• Treat an empty required value as missing unless the project explicitly says it is optional.
• Check spelling and environment selection: development, test, and production files are not interchangeable.
• For Compose, run docker compose config to inspect the resolved configuration without starting the stack. Review the output carefully because resolved values can be sensitive.

4. Identify the owner of the requested port

A port conflict is a fact, not permission to terminate a process. On macOS or Linux, inspect a common development port with lsof -i :3000. On Windows PowerShell, Microsoft documents filtering connections by local port:

Get-NetTCPConnection -LocalPort 3000 |
  Select-Object LocalAddress, LocalPort, State, OwningProcess

Get-Process -Id <OwningProcess>

Once the process is identified, decide whether it is the intended application, an abandoned development server, or another service. Prefer stopping the correct development process cleanly. Change the app's port only when that is the intended configuration, not as a way to hide an unknown listener.

5. Separate service readiness from application readiness

If the app depends on Postgres, Redis, MySQL, or Docker Compose services, inspect their state before changing code. Docker's current guide recommends docker compose config for resolved configuration, docker compose up -d to start services, and focused logs or in-container checks for live debugging. A container marked running can still be unhealthy or unable to reach another service.

• Inspect service status and health first.
• Use focused logs for the failing service instead of dumping every log.
• Test the dependency through the same network path and credentials the app uses.
• Do not run docker compose down -v as routine debugging; Docker documents that -v removes named-volume data.

6. Know when the environment is no longer the leading hypothesis

If the documented runtime, dependencies, required key names, port, and services all check out and the same application path still fails, preserve the evidence and move inward. Inspect configuration loading, the first failing call, external integration responses, error handling, and any mock or stub path. A healthy environment narrows the fault domain; it does not prove that the build is complete.

Keep a minimal evidence record

Project root:
Start command:
Observed failure and exit code:
Runtime and package-manager versions:
Dependency and lockfile state:
Missing environment-variable names (values omitted):
Requested port and owning process:
Required services and health:
Change made:
Result after one controlled retry:
Next fault domain if unchanged:

This record prevents the next person or agent from repeating random fixes and makes the environment-to-code handoff explicit.

Questions