“It works on my machine” often means the machine has a runtime, dependency, variable, database, or certificate that the project setup does not clearly describe. Treat startup as a chain of prerequisites and identify the first broken link.
1. Read the project’s intended setup
Start with README, CONTRIBUTING, repository-specific instructions, and package scripts. Check the supported runtime version (.nvmrc, engines, .tool-versions, or equivalent), the package manager, and whether Docker or another service is required. Run git status --short before setup changes so you know whether the working tree already contains edits.
Use the lockfile with the documented install command. For an npm project with a committed lockfile, npm ci installs from that lockfile and fails if the manifest and lock disagree; it does not rewrite the lockfile. Use the matching equivalent for the project’s package manager.
2. Read the first actionable error
Start the documented dev command and save the first complete error message. A stack trace may be long, but the useful cause is often the first missing executable, module, variable, or connection failure.
| Symptom | First checks |
|---|---|
command not found | Runtime and package-manager version; did the install finish? |
Cannot find module | Correct working directory, install result, and package scripts |
| Connection refused | Is the expected database, cache, or API service running and listening on this port? |
| Missing environment variable | Compare required names with the safe example file and setup docs |
| Works after a restart | Look for initialization order, stale process, or generated-file assumptions |
| Different result from CI | Compare runtime, OS, timezone, locale, services, and configured variables |
Change one thing at a time. Do not delete the lockfile, upgrade dependencies, or disable checks just to make the first error disappear. If a setup command can destroy data, inspect its effect and confirm the target is disposable before running it.
3. Configure environment safely
Projects often commit .env.example with variable names and harmless sample values, while .env or .env.local is ignored by Git and contains machine-specific values. Follow the repository’s convention. Do not copy real credentials into an issue, AI prompt, screenshot, terminal recording, or commit.
Environment variables are strings at the process boundary. Validate required values and parse booleans, numbers, and URLs deliberately in the application. In frontend frameworks, some specially prefixed variables are intentionally included in client bundles; treat those as public configuration, never as a safe place for secrets. Check your framework’s current documentation for its exact prefix and behavior.
4. Start dependencies and verify one path
If the application depends on a database, queue, or local API, follow the documented startup order and verify readiness—not merely that a container exists. Use the project’s health check or connect with its normal client. Confirm that migrations or seed data are intended for local development before running them.
Once the server starts, test one small user path in the browser or with the documented request command. Note the observed URL, status code, and relevant non-sensitive output. A page rendering does not prove that its API or database works.
5. Ask for missing setup context
If the instructions are incomplete, send a focused report: runtime and package-manager versions, exact command, first error, whether dependencies installed, and which local service is missing. Redact credentials and private data. A good setup fix may be improving the example env file or README so the next person avoids the same investigation.
Local setup checklist
- I read the project’s setup notes and checked the current Git status.
- I use the intended runtime, package manager, and lockfile.
- The install command completed without unexplained warnings or errors.
- Required environment names and services are documented and available safely.
- The development server starts and one relevant user path works.
- I did not expose a secret or erase project state while troubleshooting.
Practice
In a project you can safely inspect, compare its setup instructions with its package scripts and environment example. Write down one missing prerequisite a new teammate could hit, then propose the smallest documentation or validation change that would reveal it earlier.