What causes "target must be absolute or start with ~/" in jdx/mise?

Prefix the target with `~/` to anchor it to the home directory.

target must be absolute or start with ~/

Error message

target must be absolute or start with ~/

What it means

Thrown by `validate_file_variants` when a file entry has no variants and its `target` argument resolves to a relative path. File entries must name an absolute destination (or one starting with `~/` for the home directory), because the tool cannot safely place a file at a path relative to an unspecified working directory.

Solutions

Prefix the target with `~/` to anchor it to the home directory.
Or use a fully absolute path (`/etc/...`, `/usr/local/...`).
If the destination should vary per machine, express it with variants using absolute targets.

Example fix

// before
[[files]]
source = "zshrc"
target = ".zshrc"
// after
[[files]]
source = "zshrc"
target = "~/.zshrc"

Defensive patterns

Strategy: validation

Validate before calling

let t = shellexpand::tilde(entry.target.trim());
if !entry.target.starts_with("~/") && !Path::new(t.as_ref()).is_absolute() {
    bail!("entry {} target must be absolute or start with ~/", entry.key);
}

Type guard

fn target_is_absolute(target: &str) -> bool {
    target.starts_with("~/") || Path::new(target).is_absolute()
}

Prevention

Always anchor file targets with `~/` or `/`.
Never copy a relative source path into the target field.
Add a config lint that checks path absoluteness before apply.

When it happens

Trigger: Declaring a file entry without any `[[files.variants]]` whose target (after resolve_target_arg) is relative — e.g. `target = "dotfiles/zshrc"` or omitting path-qualifying prefixes — during validate_incoming_files or merge_file_entry.

Common situations: Hand-writing config and forgetting the leading `~/` or `/`; environment-specific configs that assume a base directory that the validator does not apply; copy-pasting a source path into the target field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/system/files.rs:233

    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 {
        let destination = variant.target.as_deref().unwrap_or(target);
        if !variant_target_is_absolute(destination) {
            bail!("variant target must be absolute or start with ~/");
        }
    }
    Ok(implied_source)
}

fn logical_source_path(key: &str) -> Result<PathBuf> {
    let path = file::replace_path(key);
    if !path.is_relative() {
        bail!(
            "destination variants require an explicit source unless the entry key is a relative source path"
        );
    }
    let mut relative = PathBuf::new();

View on GitHub (pinned to 533346cc37)