What causes "lock file did not match manifest" in FuelLabs/sway?

Run one build (or 'forc update') without --locked to sync, then commit the updated Forc.lock.

lock file did not match manifest

Error message

lock file did not match manifest

What it means

After the package graph is rebuilt from the member manifests, forc computes Lock::from_graph and diffs it against the on-disk lock; if packages were added or removed, this cause is recorded. The manifests and the lock disagree about the dependency set - normally forc rewrites Forc.lock, but with --locked it bails.

Source

Thrown at forc-pkg/src/pkg.rs:728

        let mut manifest_map = graph_to_manifest_map(manifests, &graph)?;

        // Attempt to fetch the remainder of the graph.
        let _added = fetch_graph(manifests, offline, ipfs_node, &mut graph, &mut manifest_map)?;

        // Determine the compilation order.
        let compilation_order = compilation_order(&graph)?;

        let plan = Self {
            graph,
            manifest_map,
            compilation_order,
        };

        // Construct the new lock and check the diff.
        let new_lock = Lock::from_graph(plan.graph());
        let lock_diff = new_lock.diff(&lock);
        if !lock_diff.removed.is_empty() || !lock_diff.added.is_empty() {
            new_lock_cause.get_or_insert(anyhow!("lock file did not match manifest"));
        }

        // If there was some change in the lock file, write the new one and print the cause.
        if let Some(cause) = new_lock_cause {
            if locked {
                bail!(
                    "The lock file {} needs to be updated (Cause: {}) \
                    but --locked was passed to prevent this.",
                    lock_path.to_string_lossy(),
                    cause,
                );
            }
            println_action_green(
                "Creating",
                &format!("a new `Forc.lock` file. (Cause: {cause})"),
            );
            let member_names = manifests
                .values()

View on GitHub (pinned to 47e5e902fa)

Solutions

Run one build (or 'forc update') without --locked to sync, then commit the updated Forc.lock.
If the diff is unexpected, inspect 'git diff Forc.lock' to find which manifest change caused it.
Make it a habit to commit Forc.toml and Forc.lock together in the same change.

Example fix

# before
forc build --locked   # lock file did not match manifest

# after
git add Forc.toml Forc.lock && git commit -m "feat: add dependency"
forc build --locked

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
# fail early if the lock is out of sync with the manifests
forc build
git diff --quiet Forc.lock || { echo "Forc.lock is out of date; commit the update"; exit 1; }

Prevention

Commit Forc.toml and Forc.lock together in the same change.
After pulling or merging, run a plain 'forc build' once before any --locked step.
Add a lock-freshness check step in CI before the --locked build.

When it happens

Trigger: Adding, removing or renaming a dependency or workspace member in Forc.toml without regenerating the lock; changing a path dependency location; switching git branches where Forc.toml changed but Forc.lock did not; running with --locked afterwards.

Common situations: Pull/merge updated manifests in one branch but not the lock; a teammate committed Forc.toml without Forc.lock; CI running --locked right after dependency changes.

Related errors

AI-assisted analysis of FuelLabs/sway@47e5e902fa (2026-08-16). Data as JSON: /api/errors/9d8033c0b87c59a1. Report an issue: GitHub.