Local builds pass but CI fails: how do you compare environments, lockfiles and commands?

Preserve the first failing CI command and exact versions

This applies when a development machine starts successfully but remote builds cannot find modules, scripts or configuration. Record the CI commit and operating system and ensure local checks cover the same code. Uncommitted files do not appear remotely, and filename case can behave differently across filesystems. A build in the current directory does not refute a CI failure.

Compare commits, lockfiles, directories and environment inputs

Compare runtime and package-manager versions, lockfile state and complete installation commands, including whether build-time development dependencies were omitted. Check default shell and working directory for relative-path and script-syntax differences. For environment variables, inspect names and presence only; do not print tokens or complete values into public logs.

Repeat CI installation and builds in an isolated copy

Use a separate clean copy for CI-style installation and builds, preserving the original working tree and lockfile. If using npm ci, keep the manifest and lockfile consistent and retain installation flags required when the lockfile was created. Fix specific version, path or dependency declarations with a small patch instead of disabling tests or skipping the build.

Accept the result from the target workflow on the same commit

Acceptance requires the target CI task to pass on the repair commit with the originally failing step actually executed. One necessary clean check after removing caches may help; repeatedly rerunning passing tasks does not. Report local and remote outcomes separately. Local simulation or a queued remote run does not mean CI has recovered.

This article triggered no remote workflow and read no CI secret. Follow the repository’s installation policy and required checks; fixing one missing module should not expand into a wholesale dependency upgrade. External services or restricted runners can still affect outcomes, so preserve failure evidence. An incidental successful retry does not establish that the cause disappeared.