{"record":{"id":"97ef2b81bdb8e5fc","repo":"Hmbown/CodeWhale","slug":"overlay-is-stale-run-cli-command-update-befor-97ef2b","errorCode":null,"errorMessage":"overlay is stale; run `{CLI_COMMAND} update` before install-bundle","messagePattern":"overlay is stale; run `(.+?) update` before install-bundle","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/integrations/dsh/mod.rs","lineNumber":792,"sourceCode":"    app: DshAppBundle,\n) -> Result<DshBundleRecord> {\n    let pnpm_version = match availability {\n        BundleAvailability::Available { pnpm_version } => pnpm_version.clone(),\n        BundleAvailability::NotAvailable { reason } => {\n            anyhow::bail!(\"DSH plugin path not available: {reason}\")\n        }\n    };\n    let mut doc = DshReceiptDocument::load(&paths.receipt)?;\n    let Some(mut record) = doc.current.take() else {\n        anyhow::bail!(\"DSH is not connected; run `{CLI_COMMAND} connect` first\");\n    };\n    if record.bundle.is_some() {\n        anyhow::bail!(\"bundle already installed; use `{CLI_COMMAND} update` or `remove-bundle`\");\n    }\n    let overlay_text = std::fs::read_to_string(&paths.overlay)\n        .with_context(|| format!(\"read {}\", paths.overlay.display()))?;\n    if sha256_hex(overlay_text.as_bytes()) != record.overlay_sha256 {\n        anyhow::bail!(\"overlay is stale; run `{CLI_COMMAND} update` before install-bundle\");\n    }\n    // install-bundle defaults the palette on; `update --skin false` is the\n    // off switch. `connect --skin` records the same decision for a later update.\n    let skin = true;\n    // The ocean scene follows the recorded decision (default on).\n    let ocean = record.ocean_enabled;\n    let patch_sha = bundle::write_bundle(\n        &paths.bundle_dir,\n        &codewhale_version(),\n        &overlay_text,\n        skin,\n        ocean,\n    )?;\n    let (app_source, outcomes) =\n        match bundle::install_into_profile(runner, detection, app, &paths.bundle_dir) {\n            Ok(ok) => ok,\n            Err(error) => {\n                // Leave DSH state as dsh left it; drop our half-written package.","sourceCodeStart":774,"sourceCodeEnd":810,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/integrations/dsh/mod.rs#L774-L810","documentation":"install_bundle verifies that the overlay file on disk still matches the sha256 recorded in the receipt at connect time. If the file's hash differs from record.overlay_sha256, the overlay has drifted (edited, regenerated, or replaced) and installing the bundle on top of a stale overlay would bake the wrong content into the profile, so it aborts and asks for `update` first.","triggerScenarios":"Calling `codewhale dsh install-bundle` after the overlay file at paths.overlay was modified since the last `codewhale dsh connect`/`update` — manual edits, an older Codewhale rewriting it, or sync tools reverting it.","commonSituations":"Hand-editing the overlay to tweak settings; running install-bundle after a Codewhale upgrade regenerated the overlay; restoring the overlay from a backup with different content.","solutions":["Run `codewhale dsh update` to refresh the overlay and receipt hash, then retry install-bundle.","If you intentionally edited the overlay, re-run connect/update so the recorded hash matches before installing the bundle.","Avoid hand-editing the overlay; use documented flags (`--skin`, ocean options) instead."],"exampleFix":"// before\nvim ~/.codewhale/dsh/overlay.css\ncodewhale dsh install-bundle  # Error: overlay is stale\n\n// after\ncodewhale dsh update\ncodewhale dsh install-bundle","handlingStrategy":"validation","validationCode":"let status = codewhale_dsh_status()?;\nlet overlay = std::fs::read_to_string(&status.overlay_path)?;\nif sha256_hex(overlay.as_bytes()) != status.record.as_ref().unwrap().overlay_sha256 {\n    eprintln!(\"overlay drifted; run `codewhale dsh update` first\");\n    return Err(...);\n}","typeGuard":null,"tryCatchPattern":"match install_bundle(&paths, &detection, runner, &availability, app) {\n    Err(e) if e.to_string().contains(\"overlay is stale\") => {\n        run_dsh_update()?;\n        install_bundle(&paths, &detection, runner, &availability, app)?;\n    }\n    other => other?,\n}","preventionTips":["Never hand-edit the overlay file; use documented flags.","Re-run connect/update after any tool or sync process touches the overlay.","Verify the overlay hash before scripted bundle installs."],"tags":["dsh","bundle","checksum","stale-state"],"backgroundTag":"checksum-mismatch","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}