DebuggingIntermediate3-5 min reference
Environment Debugging
"Works locally, fails in CI/staging" is rarely a code bug — it's a difference in config, data, versions, or timing between environments. This sheet is the checklist for isolating that difference fast. It pairs with Docker for QA and Linux & CLI for Testers (linked below).
The usual culprits
| Area | Check |
|---|---|
| Config / env vars | Same NODE_ENV, URLs, flags, secrets? |
| Data | Same seed/state? Missing or stale records? |
| Versions | Node/JDK/browser/dependency versions match? |
| Services | All dependencies up + reachable from this env? |
| Time / locale / TZ | Server timezone, locale, clock skew |
| Network | Firewalls, proxies, DNS, CORS origins per env |
| Resources | CI agent slower / less RAM (timing, OOM) |
| Build | Same build artifact, or rebuilt differently? |
Isolate it
- Diff the config — env vars and feature flags between the two environments first.
- Reproduce in a container (same image as CI) to remove "my machine" variables.
- Check the data — is the failing record present and in the expected state?
- Pin versions — compare lockfiles, browser, runtime.
- Read the logs in the failing env at the failure timestamp.
Common mistakes
- Assuming a code bug when it's a config/data/version difference.
- Different
.env/ secrets between local and CI that nobody diffed. - Tests depending on local data that doesn't exist in CI.
- Timezone/locale differences breaking date/number assertions.
- Ignoring that the CI agent is slower → timing-sensitive flake.
// Related resources