Local tests pass but CI fails: what to check before changing code

When local tests pass but CI fails, the first job is to identify what changed between the two environments. This checklist helps developers collect the command, runtime, dependency, secret, and filesystem clues before making a patch that may hide the real cause.

## Start with the exact failing command
Do not summarize the CI result as "tests failed." Copy the command CI ran, the first failing test, and the first useful stack trace. If CI runs a different script than the one used locally, reproduce that command first. Many failures come from a hidden difference between npm test, npm run test:ci, a build step, or a lint command that only runs in the pipeline.

## Check runtime and package manager versions
Record the runtime version, package manager version, and lockfile state. A Node, Python, PHP, or database minor version can change behavior at the edge. Package managers can also install different transitive dependencies when the lockfile is stale or ignored. If the failure started after a dependency update, compare the lockfile diff before editing application code.

## Compare environment variables and services
CI often has different secrets, feature flags, URLs, and service availability. A missing environment variable may look like an application bug until the test is run with the same configuration. Write down which variables are required, which are optional, and which should never be logged publicly. Redact values, but keep the names and whether they were present.

## Check filesystem and time assumptions
CI can reveal case-sensitive import paths, timezone assumptions, locale differences, and tests that depend on the current date. If a path works on a developer laptop but fails in Linux CI, inspect filename casing before changing logic. If a test compares formatted dates, set the timezone explicitly or make the test independent of local time.

## Decide when to patch
Patch code when the failing contract is clear and reproducible. Patch configuration when the failure only appears because the CI environment is different from the documented runtime. If the cause is still ambiguous, create a short reproduction note before editing.

## Minimal report format
- CI command
- failing test or step
- first useful error line
- local command tried
- runtime and package manager versions
- suspected difference
- next single change

This turns a red CI badge into a debugging route instead of a queue of guesses.

Local tests pass but CI fails: what to check before changing code

// COMMENTS

ON THIS PAGE