{"record":{"id":"e421eb8089a3b3b1","repo":"diem/diem","slug":"failed-to-link-module-against-its-dependencie","errorCode":null,"errorMessage":"Failed to link module {:?} against its dependencies","messagePattern":"Failed to link module (.+?) against its dependencies","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"language/tools/move-cli/src/sandbox/commands/doctor.rs","lineNumber":35,"sourceCode":"/// (3) all resources can be deserialized\n/// (4) all events can be deserialized\n/// (5) build/mv_interfaces is consistent with the global storage (TODO?)\npub fn doctor(state: &OnDiskStateView) -> Result<()> {\n    fn parent_addr(p: &Path) -> &OsStr {\n        p.parent().unwrap().parent().unwrap().file_name().unwrap()\n    }\n\n    // verify and link each module\n    let all_modules = state.get_all_modules()?;\n    let code_cache = Modules::new(&all_modules);\n    for module in &all_modules {\n        if bytecode_verifier::verify_module(module).is_err() {\n            bail!(\"Failed to verify module {:?}\", module.self_id())\n        }\n\n        let imm_deps = code_cache.get_immediate_dependencies(&module.self_id())?;\n        if bytecode_verifier::dependencies::verify_module(module, imm_deps).is_err() {\n            bail!(\n                \"Failed to link module {:?} against its dependencies\",\n                module.self_id()\n            )\n        }\n\n        let cyclic_check_result = bytecode_verifier::cyclic_dependencies::verify_module(\n            module,\n            |module_id| {\n                code_cache\n                    .get_module(module_id)\n                    .map_err(|_| PartialVMError::new(StatusCode::MISSING_DEPENDENCY))\n                    .map(|m| m.immediate_dependencies())\n            },\n            |module_id| {\n                code_cache\n                    .get_module(module_id)\n                    .map_err(|_| PartialVMError::new(StatusCode::MISSING_DEPENDENCY))\n                    .map(|m| m.immediate_friends())","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/diem/diem/blob/fc4714a8ea273b6efe8b13dbce72ea60aad9a16c/language/tools/move-cli/src/sandbox/commands/doctor.rs#L17-L53","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Republish the full consistent set: run `move sandbox publish` (optionally with --override-ordering) for all modules from source so dependents and dependencies match.","Check which module failed linking from the printed self_id and recompile it together with its dependencies.","Verify the state/storage directory actually contains all dependency modules (e.g. 0x1, 0x2 stdlib/framework if referenced).","Reset sandbox storage and republish the whole package bundle to guarantee a consistent snapshot."],"exampleFix":"// before: dependency upgraded in storage, dependents stale\nFailed to link module 0x42::app against its dependencies\n\n// after: republish the whole bundle from source\n$ move sandbox publish --storage storage build/my_pkg","handlingStrategy":"validation","validationCode":"// Ensure every dependency of the package is present in storage before linking checks\nfor dep in manifest.dependencies {\n    assert!(state.get_module_by_name(&dep.addr, &dep.name).is_some(),\n        \"dependency {} missing from storage; republish the bundle\", dep.name);\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = doctor::doctor(...) {\n    if e.to_string().contains(\"Failed to link module\") {\n        // republish full bundle to restore consistency\n        republish_bundle(pkg_root)?;\n    } else { return Err(e); }\n}","preventionTips":["Publish whole bundles, not individual modules, so dependents stay in sync","Republish dependents whenever a dependency's layout/API changes","Keep one storage directory per toolchain version"],"tags":["move","linker","dependencies","sandbox"],"backgroundTag":"module-link-failed","analyzedSha":"fc4714a8ea273b6efe8b13dbce72ea60aad9a16c","analyzedAt":"2026-09-04T21:07:05.890Z","contentChangedAt":"2026-09-04T21:07:05.890Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}