You just pushed a branch. The build runner picks it up. A minute later, you see the red X. The test you ran five times on your laptop just failed in CI. You refresh the logs, scroll to the error, and nothing looks wrong. You run the same test again locally. It passes. Again. This is the classic “works on my machine” problem, and in 2026, it is still one of the most frustrating parts of being a developer.
When a test passes locally but fails in CI, the root cause is almost always an environment mismatch. This guide walks you through the five most common culprits, gives you a numbered process to fix them, and shows you how to build a bulletproof pipeline that catches these issues before they waste your team’s time.
The Five Usual Suspects
Before you start changing random configuration files, know what you are looking for. These five categories cover the vast majority of cases where a test passes locally fails in CI.
- Environment variables and secrets. Your local
.envfile has values that the CI runner does not have. A missing API key, a different database URL, or a staging flag that defaults totruecan cause a test to behave differently. - File system and path differences. Windows uses backslashes. Linux uses forward slashes. A test that relies on a specific file path or a temp directory that already exists locally might break in a clean CI container.
- Dependency version drift. Your local
node_modulesor vendor folder might have a slightly different version of a library than what the CI pipeline installs. This is especially common with lock file conflicts or when using range-based version specifiers. - Timing and race conditions. Your local machine is fast and has plenty of RAM. The CI runner might be a shared container with limited resources. Tests that depend on setTimeout, async callbacks, or external service responses can fail when the timing is off by a few milliseconds.
- Operating system and architecture differences. Your M3 MacBook runs ARM. Your CI runner might be Intel. Or your CI runs on Ubuntu while you develop on Windows. Native extensions, compiled binaries, and Docker images can behave differently across architectures.
A Step-by-Step Diagnosis Process
When you hit the “test passes locally fails in CI” wall, follow this numbered process. Do not skip steps. Each one eliminates a layer of possible causes.
-
Reproduce the CI environment locally. Use the same Docker image or the same operating system that your pipeline uses. If your CI runs on
ubuntu:22.04, spin up that exact image and run your tests inside it. This is the single most effective debugging step you can take. -
Check the environment variables. Print all environment variables at the start of your test suite. Compare the output from your local run with the output from the CI logs. Look for missing keys, different values, or variables that are set to empty strings.
-
Freeze your dependencies. Make sure your lock file is committed and up to date. Run
npm cior the equivalent for your package manager. This installs exact versions, not ranges. If the CI pipeline usesnpm installinstead ofnpm ci, that is likely your problem. -
Add explicit timeouts and retries. For any test that hits a network endpoint, a database, or a file system operation, set a timeout that is generous enough for a resource-constrained CI runner. Use libraries like
jest-retryorpytest-rerunfailuresto automatically rerun flaky tests. -
Isolate the failing test. Run only the failing test in isolation. If it passes in isolation but fails when the full suite runs, you have a test ordering or state pollution problem. Clean up shared state in
beforeEachorsetupblocks, not just inafterAllorteardown.
Common Mistakes and Their Fixes
Here is a table that maps the most common mistakes to their specific fixes. Use it as a reference when you are deep in the logs.
| Mistake | Symptom | Fix |
|---|---|---|
Missing .env file in CI |
Test fails with “undefined” or connection refused | Store secrets in CI variables, not in the repository |
| Hardcoded file paths | Test passes on macOS, fails on Linux | Use path.join() and OS-agnostic separators |
| No lock file committed | Different versions installed locally vs. CI | Commit the lock file and use npm ci |
| Async test without done callback | Test passes locally, times out in CI | Add a timeout parameter and use async/await properly |
| Test relies on local database state | Test passes because local DB has pre-seeded data | Use in-memory databases or transactional test fixtures |
Why Your CI Pipeline Is Different From Your Laptop
Your laptop is a personalized environment. You have installed tools over the years. You have global packages. You have environment variables set in your shell profile. Your Docker daemon might be running. Your database might have leftover data from the last time you ran the tests.
A CI pipeline starts from scratch every time. That is the whole point. It is a clean, isolated environment that mimics production. But that cleanliness is also what causes the mismatch. When your test passes locally fails in CI, it is often because your local environment is hiding a bug that the clean environment exposes.
Think of it this way. Your local setup is like a messy desk where you know exactly where everything is. The CI runner is a blank desk with nothing on it. If your test assumes a file exists, or a service is running, or a certain package is installed globally, it will fail on the blank desk.
“The only difference between a flaky test and a real bug is how long it takes to reproduce it. If you cannot reproduce it in a clean environment, you have not found the root cause yet.” This is a hard truth that every DevOps engineer learns eventually.
How to Build a Bulletproof Pipeline
You can stop fighting these mismatches by designing your pipeline to catch them early. Here are three concrete changes you can make this week.
First, use the same operating system and architecture for local development that you use in CI. If your team uses MacBooks but your CI runs on Linux, tell your team to use Docker for local development. Spin up a docker-compose.yml that matches the CI environment exactly. Run your tests inside that container, not on your host machine.
Second, add a pre-commit hook that runs the exact same commands your CI pipeline runs. If your CI runs npm test -- --ci, make your pre-commit hook run that same command. If it fails locally, it will never reach the pipeline.
Third, log everything. At the start of your CI pipeline, print the OS version, the kernel architecture, the Node.js version, the available memory, and the list of environment variables (without exposing secrets). Store these logs alongside the test results. When a test fails, you have a complete picture of the environment it ran in.
For more on handling tricky runtime errors, check out our guide on common JavaScript debugging tricks every developer should know. If you suspect a memory issue is causing your tests to behave differently, read about diagnosing and fixing memory leaks in web applications.
The One Tool That Changes Everything
If you take only one thing from this guide, let it be this. Use a containerized local environment that is identical to your CI environment. Tools like Dev Containers, Docker Compose, and Nix have made this trivial in 2026.
When your local environment matches your CI environment, the phrase “test passes locally fails in CI” stops being a problem. It becomes a rare exception that points to a real infrastructure issue, not a daily frustration.
Set up your Dockerfile or .devcontainer.json today. Run your tests inside it. Watch how many of those red Xs turn green.
Making Your Tests Reliable for the Whole Team
A test that only passes on your machine is not a test. It is a liability. Every time a teammate pulls your branch and sees a failure, they lose trust in the pipeline. That trust is hard to rebuild.
The goal is not to eliminate every single flaky test. The goal is to make the pipeline so consistent that when it turns red, the team knows something is actually broken. That is the power of fixing the environment mismatch.
Start with the diagnosis process above. Pick one test that fails in CI but passes locally. Run through the five steps. You will find the cause within an hour. Then fix the root cause, not the symptom. Do not add a retry loop. Do not skip the test. Fix the environment variable, the file path, or the dependency version.
Your future self, and your whole team, will thank you.
