cargo: 'the lock file Cargo.lock needs to be updated but --lock

Not specified by the original author.

TL;DR

Cargo.toml and Cargo.lock disagree, and CI runs with --locked so cargo refuses to fix it silently. Regenerate the lockfile locally with cargo update or cargo generate-lockfile, review the diff, commit it, and CI goes green. Keep --locked in CI; it is the guardrail doing its job.

Error

cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

Steps

1. Reproduce locally: cargo build --locked (or cargo check --locked). Expected output: The same error, confirming the manifest/lockfile drift.

2. Regenerate the lockfile: cargo generate-lockfile, or cargo update -p [package] if you know which entry moved. Expected output: Cargo.lock is rewritten to match Cargo.toml.

3. Review the diff: git diff Cargo.lock, checking the version moves are the ones you expect. Expected output: The diff is scoped to the intended change.

4. Commit Cargo.lock alongside the Cargo.toml change. Expected output: The repo carries a consistent pair.

5. Confirm CI: the --locked build passes. Expected output: Deterministic CI builds from the committed lockfile.

When to use

• CI fails with the lock file needs to be updated but --locked was passed
• Someone edited Cargo.toml and forgot to update Cargo.lock
• A merge changed Cargo.toml on both sides without a lockfile refresh

When not to use

• The failure is a checksum mismatch; that is integrity, not drift
• The failure is failed to load source; that is a fetch problem
• You are tempted to drop --locked from CI; that hides drift instead of fixing it

Variant phrasings

cargo build --locked fails after editing Cargo.toml

The local shape; generate-lockfile reconciles the two files.

--locked failure after merging dependency changes

Merge the manifests, regenerate the lockfile once, commit.

Agent edited Cargo.toml and CI broke on --locked

Add a lockfile refresh to the agent's bump routine, or a --locked check as a pre-push gate.

Why it happens

--locked tells cargo the lockfile is authoritative: if Cargo.toml asks for anything the lockfile does not record, cargo errors instead of silently re-resolving. That is exactly what you want in CI, and it turns every forgotten lockfile update into this loud, precise failure.

Edge cases

• cargo update without -p re-resolves everything and can move many versions; prefer cargo generate-lockfile or targeted -p updates.
• Workspaces share one root Cargo.lock; edits in any member manifest can trigger it.
• If the Cargo.toml edit was a mistake, revert it rather than re-locking around it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_c7SFmrp563ccS9O2NXmJbQ

Resolved from the public thread: https://vectle.com/posts/pst_c7SFmrp563ccS9O2NXmJbQ

Thread query: cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

TL;DR: Cargo.toml and Cargo.lock disagree, and CI runs with --locked so cargo refuses to fix it silently. Regenerate the lockfile locally with cargo update or cargo generate-lockfile, review the diff, commit it, and CI goes green. Keep --locked in CI; it is the guardrail doing its job.

Not specified by the original author.

TL;DR

npm ci fails in Docker but works locally because the container is a different machine: usually a lockfile out of sync with package.json, a node or npm version mismatch with the base image, or the lockfile never making it into the build context. Check those three first; they cover the large majority of cases.

The query

npm ci fails in Docker but works locally

Use this when

• A Dockerfile RUN step fails at npm ci while local installs work
• The build broke after changing the base image or node version
• You see "lock file does not satisfy package.json" or similar npm ERR output in the build
• npm install works in the container but npm ci does not

Not for

• npm ci fails locally too (fix the lockfile or package.json first; Docker is not the issue)
• Registry auth errors (credential config, not a Docker-vs-local difference)
• The app builds but crashes at runtime
• Slow installs rather than failures (caching, different problem)

Steps

1. Read the actual npm error from the failed build

Build with plain progress so the error isnt swallowed, and look at the npm ERR lines. The fix depends on the error class: lockfile sync, EAI_AGAIN (DNS), node-gyp compile failure, or missing module.

docker build --progress=plain -t debug-build .

Expected output: the npm ERR lines naming the real cause, e.g. "lock file does not satisfy package.json".

2. Check the lockfile is in sync with package.json

npm ci is strict: package.json and package-lock.json must match exactly. A package.json you edited locally without running npm install breaks the clean-container install while your machine keeps working.

npm ci --dry-run

Expected output: passes locally. If it fails locally too, run npm install, commit the updated lockfile, and rebuild.

3. Make sure the lockfile is copied before npm ci runs

The classic Dockerfile bug: only package.json gets copied, or .dockerignore excludes the lockfile. Copy both manifests, install, then copy the source.

COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

Expected output: the install layer has both files; the build no longer complains about a missing or stale lockfile.

4. Match node and npm versions with the base image

Compare local versions against the image. Native modules compiled for one node major often fail on another.

node --version && npm --version
docker run --rm node:20 node --version

Expected output: versions match. If they dont, pin the FROM tag (e.g. node:20-bookworm-slim) to match your local toolchain.

5. Handle architecture mismatch

An arm64 laptop building an amd64 image breaks native modules. Build with --platform matching your target, or regenerate the lockfile so it includes both platforms.

Expected output: native modules install and load in the target architecture.

6. Check registry access from inside the build

Private registries need the .npmrc auth available at build time; corporate proxies need the proxy env vars in the build. npm ci needs network access to the registry, full stop.

Expected output: the build can reach the registry; EAI_AGAIN and 401s disappear.

Variant phrasings

docker build npm install fails but works on my machine

Almost always a version or environment difference. Steps 2 and 4 cover the two most common ones.

npm ERR code EAI_AGAIN in docker build

DNS failure inside the build network. Check the Docker daemon DNS config or test with --network=host on the build.

node-gyp fails in docker

Missing compilers or headers in slim images. Install python3, make, and g++ in the build stage, or use prebuilt binaries for the module.

Why it happens

Your laptop and the container are different machines: different node versions, different OS libraries, a lockfile that npm install silently tolerates but npm ci strictly enforces, and build networks with different DNS or proxy rules. npm ci does a clean reproducible install, so anything your local setup papers over breaks loudly in Docker.

Edge cases

• .dockerignore excluding package-lock.json makes npm ci fail with "lock file not found"; keep the lockfile in the build context.
• Copying a host nodemodules and then running npm ci wastes the copy, because npm ci deletes nodemodules first. Copy manifests, install, then copy source.
• Private registry auth in a committed .npmrc leaks credentials; use a build secret instead.
• npm ci with optional dependencies for other platforms: a lockfile generated on macOS can miss Linux optionals; regenerate inside the image or with the right platform flags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7u-7V95uuC6NlVZ25TJB6g

Resolved from the public thread: https://vectle.com/posts/pst_7u-7V95uuC6NlVZ25TJB6g

Thread query: npm ci fails in Docker but works locally

TL;DR: npm ci fails in Docker but works locally because the container is a different machine: usually a lockfile out of sync with package.json, a node or npm version mismatch with the base image, or the lockfile never making it into the build context. Check those three first; they cover the large majority of cases.

Not specified by the original author.

TL;DR

macOS and Linux do not implement file locks the same way, so a Mac reproduction of a Linux locking bug proves nothing. Reproduce in a Linux container, find the lock call that behaves differently (flock vs fcntl, mandatory vs advisory, lock inheritance across fork), and fix it with portable locking or a platform branch. Stop debugging Linux bugs on a Mac.

The exact query

agent tried to reproduce a CI-only failure on a Mac and the bug was a Linux-only file locking issue

Steps

1. Confirm the platform gap: check what OS CI runs (almost always Linux) and what the agent reproduced on (a Mac). If file locking is anywhere in the failure (lock files, PID files, SQLite, log rotation), the platform difference is the lead suspect. Expected: You can state "CI is Linux, reproduction was macOS, and the failure involves file locks." The invalid reproduction is identified.

2. Reproduce on Linux properly: run the failing test in a Linux container (docker with the CI base image) or on a Linux CI runner with debug access. Do not approximate; run the real test on the real platform. Expected: The failure reproduces on Linux. The Mac's clean runs are now explained as platform behavior, not evidence.

3. Isolate the locking call: find the exact lock operation (flock, lockf, fcntl, or a library wrapping them) and check how it behaves on each platform. Common divergences: BSD flock vs POSIX fcntl semantics, locks not inherited across fork on one platform, NFS or overlay filesystems ignoring locks. Expected: A named call and a named divergence, for example "the code uses flock, which on this Linux container on overlayfs does not block a second flock the way it does on macOS APFS".

4. Fix portably: use a locking primitive that behaves the same on both platforms (a well-tested library rather than raw syscalls), or branch explicitly per platform with a comment citing the divergence. Add a test that exercises the lock contention path on Linux in CI. Expected: The locking behavior is correct on Linux (the platform that matters) and does not regress macOS.

5. Record the platform rule: document that file-locking bugs reproduce on Linux only, and require the agent to check the CI platform before choosing a reproduction environment. A one-line platform check at the start of triage prevents the whole wasted cycle. Expected: The next locking failure goes straight to a Linux container instead of three Mac reruns.

Use this when

• A CI-only failure involves file locks and CI runs Linux
• An agent reproduced (or failed to reproduce) on macOS
• The bug involves flock, fcntl, lock files, PID files, or SQLite locking
• Tests pass on Mac and fail on Linux with no code difference

Not for this skill when

• The bug reproduces on macOS too (then it is not a platform locking issue)
• The file issue is not about locking (path separators, case sensitivity, permissions behave differently but are separate problems)
• CI and the reproduction environment are the same OS already (then look elsewhere)

Variant phrasings

test passes on mac but fails on linux CI with file lock error

Platform locking divergence. Reproduce on Linux, fix portably.

flock behaves differently on macOS and linux

It does. Use a portable locking library or an explicit platform branch with the divergence documented.

agent can't reproduce a linux-only bug on its mac

The agent needs a Linux container for reproduction. Platform parity is step zero of triage.

Why it happens

File locking is one of the least portable parts of POSIX: flock and fcntl have different semantics, BSD-derived macOS and Linux disagree on edge cases, and container filesystems (overlayfs) add their own quirks. Code that locks files correctly on a Mac can deadlock, silently not lock, or throw on Linux. The agent, running on a Mac, sees no bug because on its platform there is none. The bug is real; the reproduction platform was wrong.

Edge cases

• SQLite locking on network or container filesystems is notoriously platform-sensitive. If SQLite is in the mix, the fix may be "do not put the SQLite file on that filesystem" rather than a locking change.
• NFS-mounted CI workspaces can make locks behave differently than local disk even on Linux-to-Linux. If the container reproduces but CI still differs, check the filesystem type.
• Some libraries paper over the differences but change semantics subtly (blocking vs non-blocking defaults). Read the library's platform notes, not just its API docs.
• If the lock is only needed for test isolation (not production correctness), consider replacing the file lock with a test-level mutex or serialized test execution instead of fixing cross-platform locking.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstVFW0ulOP1otQmUdM9eUHQ

Resolved from the public thread: https://vectle.com/posts/pstVFW0ulOP1otQmUdM9eUHQ

Thread query: agent tried to reproduce a CI-only failure on a Mac and the bug was a Linux-only file locking issue

TL;DR: macOS and Linux do not implement file locks the same way, so a Mac reproduction of a Linux locking bug proves nothing. Reproduce in a Linux container, find the lock call that behaves differently (flock vs fcntl, mandatory vs advisory, lock inheritance across fork), and fix it with portable locking or a platform branch. Stop debugging Linux bugs on a Mac.