files: cannot diff these entries, fix them manually: {}

Error message

files: cannot diff these entries, fix them manually:
{}

What it means

In mise's `files diff` command (src/system/files.rs:3033), per-entry diffs are attempted; when printing a diff fails for an entry (e.g. the entry cannot be rendered or diffed), the command collects the problems and bails listing them all, telling the user to fix them manually. It fires only after individual diff attempts failed, aggregating every failing entry into one message.

Source

Thrown at src/system/files.rs:3033

            },
            _ => None,
        };
        match check_rendered(req, rendered.as_deref()) {
            Ok(FileState::Applied) => continue,
            Ok(_) => {}
            Err(err) => {
                problems.push(format!("  \"{}\": {err}", req.target_raw));
                continue;
            }
        }
        changed = true;
        miseprintln!("dotfile differs: {}", req.target.display_user());
        if let Err(err) = print_diff(req, rendered.as_deref()) {
            problems.push(format!("  \"{}\": {err}", req.target_raw));
        }
    }
    if !problems.is_empty() {
        bail!(
            "files: cannot diff these entries, fix them manually:\n{}",
            problems.join("\n")
        );
    }
    if !changed {
        info!("files: all files are applied");
    }
    Ok(())
}

const DOTFILES_PART: &str = "dotfiles";

/// Every path `apply_one` may create, replace, or remove for `req`, with how
/// deeply to capture it first: a path that gets replaced is captured whole,
/// a directory that stays a directory only by existence.
fn touched_paths(req: &FileRequest) -> Result<Vec<(PathBuf, Capture)>> {
    let mut paths: IndexMap<PathBuf, Capture> = IndexMap::new();
    for dir in missing_ancestors(&req.target) {

View on GitHub (pinned to afd2eddd3a)

Solutions

Fix each listed entry manually (the message names them by their raw target path)
Inspect the per-entry cause — the underlying err from print_diff is embedded in the listing
If a template command fails, fix the command in the template source, then rerun diff
Remove or correct the broken entry in mise.toml if it is obsolete

Example fix

# output
# files: cannot diff these entries, fix them manually:
#   "~/.zshrc": template command failed

# after: fix the template command in the source, then
mise bootstrap dotfiles diff

Defensive patterns

Strategy: try-catch

Validate before calling

for (const e of entries) {
  if (e.mode === 'template' && templateHasCommands(e.source)) {
    console.warn(`entry ${e.target} renders commands; diff may fail`);
  }
}

Try / catch

try {
  await diff();
} catch (e) {
  if (String(e).startsWith('files: cannot diff these entries')) {
    // parse the listed entries from the message and fix them manually
  } else throw e;
}

Prevention

Keep template embedded commands working (test them standalone)
Fix entries reported by `dotfiles status` before running diff
Avoid unreadable or missing sources/targets in managed entries

When it happens

Trigger: `mise bootstrap dotfiles diff` where print_diff (or rendering within it) returns Err for one or more FileRequests — e.g. a template whose rendering executes a failing command, or unreadable/unrenderable entries — producing a non-empty `problems` list.

Common situations: A template mode entry whose embedded command fails during rendering; a target/source pair in an inconsistent state (missing source, unreadable file); entries modified so drastically that the differ cannot produce output.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/9bb3975126b21fa8. Report an issue: GitHub.