jdx/mise · error

dotfiles: {key} could not be tracked: {reason}

Error message

dotfiles: {key} could not be tracked: {reason}

What it means

After activating a tracked declaration, mise verifies each path actually landed in the tracked set. If a path is still reported invalid (or the declaration was never loaded), track aborts with 'could not be tracked' and includes the per-path invalid reason captured in `tracked.invalid`.

Source

Thrown at src/cli/dotfiles/track.rs:352

}

/// Checks that every declared entry is active and saves their baseline.
async fn activate_and_baseline(declared: &[(String, PathBuf)]) -> Result<()> {
    let config = Config::reset().await?;
    let tracked = TrackedSet::from_config(&config)?;
    for (key, target) in declared {
        let path = normalize_target(target);
        let active = tracked
            .entry_for(&path)
            .is_some_and(|entry| entry.path == path);
        if !active {
            let reason = tracked
                .invalid
                .iter()
                .find(|invalid| invalid.path == display_path(&path))
                .map(|invalid| invalid.reason.clone())
                .unwrap_or_else(|| "the declaration was not loaded".into());
            bail!("dotfiles: {key} could not be tracked: {reason}");
        }
    }
    baseline(&tracked, declared).await
}

/// Saves the baseline checkpoint of newly tracked paths; a failure fails
/// the enrollment, since an untracked file must never look protected.
async fn baseline(tracked: &TrackedSet, declared: &[(String, PathBuf)]) -> Result<()> {
    if !crate::config::Settings::get().history.enabled {
        warn!("dotfiles: history is disabled (history.enabled = false); no baseline saved");
        return Ok(());
    }
    let store = Store::open()?;
    if let Some(reason) = store.unavailable() {
        bail!("dotfiles: cannot save the baseline: {reason}");
    }
    // A capture wrapper owns the operation lock until this child exits. It
    // reloads enrollment and explicitly saves all current tracked files in

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Read the `{reason}` in the message — it names the exact invalid entry cause
2. Fix the declaration file entry (path spelling, excluded rule, portability)
3. Ensure the declaration file is valid TOML and in a location mise loads
4. Retry track after correcting, then let the baseline save run

mise bootstrap dotfiles status --target "$path" >/dev/null 2>&1 && echo tracked || echo 'not tracked / invalid'

if out=$(mise bootstrap dotfiles track "$p" 2>&1); then :; else
  echo "track failed for $p: $out"  # reason names the invalid entry
fi

When it happens

Trigger: `dotfiles track` -> activate_and_baseline: the path remains in `tracked.invalid` after activation (e.g. excluded by a rule, unresolvable, outside allowed roots), or the declaration edit failed to load so no entry exists.

Common situations: Trying to track a path disallowed by portability/exclusion rules; a malformed declaration TOML that silently failed to load; symlinks pointing outside allowed locations.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• [dotfiles]."{req.target_raw}": mode symlink-each requires a
• "{path_raw}".{id}: block/source and line are mutually exclus
• "{path_raw}".{id}: no recognized operation (block, source, o
• "{path_raw}".{id}: position is only valid with line, ignorin
• "{path_raw}".{id}: block and source are mutually exclusive,

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