diem/diem · error

Failed to link module {:?} against its dependencies

Error message

Failed to link module {:?} against its dependencies

What it means

During `move doctor`, after each module passes standalone verification, the doctor links it against its immediate dependencies via bytecode_verifier::dependencies::verify_module. This bail fires when linking fails: the module references structs/functions from a dependency that do not exist or are incompatible in the stored state. It means the module set in the sandbox is mutually inconsistent.

Source

Thrown at language/tools/move-cli/src/sandbox/commands/doctor.rs:35

/// (3) all resources can be deserialized
/// (4) all events can be deserialized
/// (5) build/mv_interfaces is consistent with the global storage (TODO?)
pub fn doctor(state: &OnDiskStateView) -> Result<()> {
    fn parent_addr(p: &Path) -> &OsStr {
        p.parent().unwrap().parent().unwrap().file_name().unwrap()
    }

    // verify and link each module
    let all_modules = state.get_all_modules()?;
    let code_cache = Modules::new(&all_modules);
    for module in &all_modules {
        if bytecode_verifier::verify_module(module).is_err() {
            bail!("Failed to verify module {:?}", module.self_id())
        }

        let imm_deps = code_cache.get_immediate_dependencies(&module.self_id())?;
        if bytecode_verifier::dependencies::verify_module(module, imm_deps).is_err() {
            bail!(
                "Failed to link module {:?} against its dependencies",
                module.self_id()
            )
        }

        let cyclic_check_result = bytecode_verifier::cyclic_dependencies::verify_module(
            module,
            |module_id| {
                code_cache
                    .get_module(module_id)
                    .map_err(|_| PartialVMError::new(StatusCode::MISSING_DEPENDENCY))
                    .map(|m| m.immediate_dependencies())
            },
            |module_id| {
                code_cache
                    .get_module(module_id)
                    .map_err(|_| PartialVMError::new(StatusCode::MISSING_DEPENDENCY))
                    .map(|m| m.immediate_friends())

View on GitHub (pinned to fc4714a8ea)

Solutions

1. Republish the full consistent set: run `move sandbox publish` (optionally with --override-ordering) for all modules from source so dependents and dependencies match.
2. Check which module failed linking from the printed self_id and recompile it together with its dependencies.
3. Verify the state/storage directory actually contains all dependency modules (e.g. 0x1, 0x2 stdlib/framework if referenced).
4. Reset sandbox storage and republish the whole package bundle to guarantee a consistent snapshot.

Example fix

// before: dependency upgraded in storage, dependents stale
Failed to link module 0x42::app against its dependencies

// after: republish the whole bundle from source
$ move sandbox publish --storage storage build/my_pkg

// Ensure every dependency of the package is present in storage before linking checks
for dep in manifest.dependencies {
    assert!(state.get_module_by_name(&dep.addr, &dep.name).is_some(),
        "dependency {} missing from storage; republish the bundle", dep.name);
}

if let Err(e) = doctor::doctor(...) {
    if e.to_string().contains("Failed to link module") {
        // republish full bundle to restore consistency
        republish_bundle(pkg_root)?;
    } else { return Err(e); }
}

When it happens

Trigger: `move doctor` on a state directory where a module's immediate dependency is missing, an older incompatible version of a dependency is stored, or dependency bytecode was replaced after this module was compiled.

Common situations: Publishing a new version of a dependency directly into storage without republishing dependents; deleting or overwriting a dependency module file; sharing sandbox state between packages compiled against different dependency versions.

Related errors

• Duplicate dependency module for {}
• Failed to verify module {:?}
• Cyclic module dependencies are detected with module {} in th
• Type formal '{}'' already bound
• Unbound type parameter {}

AI-assisted analysis of diem/diem@fc4714a8ea (2026-09-04). Data as JSON: /api/errors/e421eb8089a3b3b1. Report an issue: GitHub.