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

Error message

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

What it means

Dotfile targets must resolve to an absolute path or begin with `~/` so mise can anchor them to your home directory. `resolve_target_arg` expands `~`; if the result is still relative, the declaration is rejected during preflight because relative targets are ambiguous (they would depend on the process working directory).

Source

Thrown at src/system/files.rs:581

                        "source"
                            | "content"
                            | "mode"
                            | "exclude"
                            | "manifest"
                            | "autosave"
                            | "encrypt"
                            | "variants"
                            | "enabled"
                    ) {
                        bail!(
                            "unknown dotfile key {key:?} for {target} in {}",
                            path.display()
                        );
                    }
                }
            }
            if resolve_target_arg(&target).is_relative() {
                bail!("dotfile target must be absolute or start with ~/: {target}");
            }
            if let FileTomlEntry::Table {
                source,
                content,
                mode,
                manifest,
                exclude,
                ..
            } = entry
            {
                if content.is_some() && (mode.is_some() || exclude.is_some() || manifest.is_some())
                {
                    bail!(
                        "dotfile {target}: inline content does not support mode, exclude, or manifest"
                    );
                }
                let mode = match mode.as_deref() {
                    Some(value) => FileMode::parse(value).ok_or_else(|| {

View on GitHub (pinned to afd2eddd3a)

Solutions

Prefix the target with `~/` (or use the absolute path) in the dotfiles table key.
If the file lives outside $HOME, use its absolute path, e.g. `/etc/profile.d/foo.sh`.
Re-check generated/templated config so the target key always includes the leading `~/` or `/`.

Example fix

// before
[dotfiles.".config/kitty/kitty.conf"]
source = "kitty.conf"

// after
[dotfiles."~/.config/kitty/kitty.conf"]
source = "kitty.conf"

Defensive patterns

Strategy: validation

Validate before calling

function assertAbsoluteOrHomeTarget(target) {
  if (!(target.startsWith('~/') || target.startsWith('/')))
    throw new Error(`dotfile target must be absolute or start with ~/: ${target}`);
}

Try / catch

try {
  applyDotfiles();
} catch (e) {
  if (/must be absolute or start with ~\//.test(e.message)) {
    console.error('Prefix the offending dotfiles table key with ~/ or /');
  } else throw e;
}

Prevention

Always write dotfile targets with an explicit `~/` or absolute prefix
When generating config programmatically, assert the prefix before writing the file
Code-review dotfile additions for path style consistency

When it happens

Trigger: Declaring a dotfile whose key is a relative path, e.g. `[dotfiles.".bashrc"]` or `[dotfiles."config/kitty/kitty.conf"]`, with no leading `/` or `~/`.

Common situations: Copying examples from tools that use paths relative to a dotfiles repo, abbreviating `~/` away, or templating the target from a variable that lost its prefix.

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/d6d95b8f339ee03d. Report an issue: GitHub.