target overrides are not supported with mode = "track"

Error message

target overrides are not supported with mode = "track"

What it means

Thrown by `validate_file_variants` when a file entry that uses `mode = "track"` (tracking an existing destination file) also declares one or more `target` overrides on its variants. Target overrides redirect where a variant is written, which is incompatible with tracking mode, so the combination is rejected at config validation time.

Solutions

Remove the `target` overrides from all variants of the tracked entry.
If the variant truly needs a different destination, split it into a separate non-track file entry.
If you need per-variant destinations, switch the entry out of track mode to the appropriate managed/symlink mode.

Example fix

// before
[[files]]
source = "gitconfig"
mode = "track"
[[files.variants]]
target = "~/.config/git/config"
// after
[[files]]
source = "gitconfig"
mode = "track"
# no per-variant target overrides

Defensive patterns

Strategy: validation

Validate before calling

// config-time check before loading entries
if entry.mode == "track" && entry.variants.iter().any(|v| v.target.is_some()) {
    bail!("tracked entry {} has variant target overrides", entry.key);
}

Type guard

fn track_entry_has_target_overrides(entry: &FileEntry) -> bool {
    entry.mode.as_deref() == Some("track")
        && entry.variants.iter().any(|v| v.target.is_some())
}

Prevention

Keep tracked entries variant-free or override-free by convention.
Split tracking entries and deployment entries into separate keys.
Validate config with a lint pass before running apply/sync.

When it happens

Trigger: Declaring a file entry with mode = "track" where any variant sets a `target` field — detected by `variants.iter().any(|v| v.target.is_some())` combined with `mode == Some("track")`, during validate_incoming_files or merge_file_entry.

Common situations: Copy-pasting a variants block from a symlink/managed entry into a tracked entry; intending to track one file but additionally deploy a variant elsewhere and assuming both features compose; migrating an entry from managed to track mode without cleaning up target overrides.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/15135e0abe55815d. Report an issue: GitHub.

Appendix: source

Thrown at src/system/files.rs:217

            .map_err(serde::de::Error::custom)?;
        Ok(Self { target, selector })
    }
}

/// Validate selector combinations and destination syntax before selecting a variant.
/// Returns a `dotfiles.root`-relative implied source for a logical entry key.
fn validate_file_variants(
    target: &str,
    source: Option<&str>,
    content: Option<&str>,
    mode: Option<&str>,
    variants: &[FileVariant],
) -> Result<Option<PathBuf>> {
    let selectors: Vec<_> = variants.iter().map(|v| v.selector.clone()).collect();
    crate::system::history::select::validate(&selectors)?;
    let has_target_override = variants.iter().any(|v| v.target.is_some());
    if has_target_override && mode == Some("track") {
        bail!("target overrides are not supported with mode = \"track\"");
    }
    if has_target_override && content.is_some() {
        bail!("destination variants with inline content are not supported");
    }
    let implied_source = if has_target_override && source.is_none() {
        if !variants.iter().all(|v| v.target.is_some()) {
            bail!(
                "destination variants require an explicit source when any variant uses the entry key as its target"
            );
        }
        Some(logical_source_path(target)?)
    } else {
        None
    };
    if variants.is_empty() && resolve_target_arg(target).is_relative() {
        bail!("target must be absolute or start with ~/");
    }
    for variant in variants {

View on GitHub (pinned to 533346cc37)