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

Use an absolute path (e.g. /home/user/.zshrc) for the target.

{target_raw}: target must be absolute or start with ~/

Error message

{target_raw}: target must be absolute or start with ~/

What it means

Dotfile targets must resolve to a managed location outside the working directory. Each raw target string is passed through resolve_target_arg and normalized; if the resulting path is still relative (neither an absolute path nor starting with `~/`), run_inner bails. This prevents adding dotfiles with cwd-dependent paths, which would make management location-sensitive.

Source

Thrown at src/cli/dotfiles/add.rs:159

            }
        }
        let config_path = resolve_target_config_path(ConfigPathOptions {
            global: self.global || !self.local,
            path: self.path.clone(),
            env: None,
            cwd: None,
            prefer_toml: true,
            prevent_home_local: true,
        })?;

        let mut planned = vec![];
        let managed_edits = system::edits::edits_from_config(&config)?;
        for target_raw in &self.targets {
            let target = system::files::resolve_target_arg(target_raw)
                .components()
                .collect::<PathBuf>();
            if target.is_relative() {
                bail!("{target_raw}: target must be absolute or start with ~/");
            }
            if managed
                .iter()
                .any(|req| req.mode == FileMode::Track && req.target == target)
            {
                bail!(
                    "{target_raw}: tracked in place; pass `--mode copy` after `mise bootstrap dotfiles untrack {target_raw}` to seed a source instead"
                );
            }
            if managed_edits.iter().any(|req| {
                system::files::matches_target(
                    &req.path,
                    &req.path_raw,
                    std::slice::from_ref(target_raw),
                )
            }) {
                bail!(
                    "{target_raw}: target is already managed by [dotfiles] edits; remove or rename those entries before adding a whole-file dotfile"

View on GitHub (pinned to afd2eddd3a)

Solutions

Use an absolute path (e.g. /home/user/.zshrc) for the target.
Use `~/`-prefixed paths, which resolve_target_arg expands against HOME.
Compute the absolute path in your script: `mise bootstrap dotfiles add "$HOME/.zshrc"`.

Example fix

// before
mise bootstrap dotfiles add .zshrc
// after
mise bootstrap dotfiles add ~/.zshrc

Defensive patterns

Strategy: validation

Validate before calling

function isValidTarget(raw) {
  return raw.startsWith('~/') || raw.startsWith('/');
}
if (!isValidTarget(target)) throw new Error(`use absolute or ~/${''} path: ${target}`);

Prevention

Always write dotfile targets as `~/...` or absolute paths.
In scripts, prefix with "$HOME" or expand `~` before invoking the CLI.
Never rely on cwd-relative resolution for dotfile targets.

When it happens

Trigger: Running `mise bootstrap dotfiles add <relative/path>` where the path is relative and does not expand to an absolute path or `~/...`. E.g. `dotfiles add .zshrc` from home.

Common situations: Typing shell-style shorthand paths assuming cwd-relative resolution works; script variables that hold relative paths; copy-pasting paths without the leading `~` or `/`.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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