source is required for the home directory itself

Error message

source is required for the home directory itself

What it means

When a non-track dotfile declares no `source` and no `content`, mise infers the source path from the target's path relative to $HOME (target `~/.gitconfig` implies source `<dotfiles_root>/gitconfig`). This inference cannot work for the home directory itself: the relative path is empty, so `implied_source` fails with this message.

Source

Thrown at src/system/files.rs:977

            FileMode::Symlink
        }
    }
}

pub(crate) fn dotfiles_root() -> PathBuf {
    file::replace_path(&Settings::get().dotfiles.root)
}

pub(crate) fn implied_source(target: &Path) -> Result<PathBuf> {
    let home: &Path = &dirs::HOME;
    let rel = target.strip_prefix(home).map_err(|_| {
        eyre::eyre!(
            "source is required for targets outside $HOME: {}",
            target.display_user()
        )
    })?;
    if rel.as_os_str().is_empty() {
        bail!("source is required for the home directory itself");
    }
    Ok(dotfiles_root().join(rel))
}

pub(crate) fn source_is_implied(req: &FileRequest) -> bool {
    if req.mode == FileMode::Content {
        return false;
    }
    match implied_source(&req.target) {
        Ok(source) => source == req.source,
        Err(_) => false,
    }
}

pub(crate) fn resolve_target_arg(target: &str) -> PathBuf {
    lexical_normalize(&file::replace_path(target))
}

View on GitHub (pinned to afd2eddd3a)

Solutions

Target a concrete file or subdirectory (e.g. `~/.gitconfig`) so the source can be inferred.
Add an explicit `source` key if you genuinely need a special target.
Remove the entry if it was accidental (e.g. a wildcard or templating artifact resolving to `~`).

Example fix

// before
[dotfiles."~"]

// after
[dotfiles."~/.gitconfig"]

Defensive patterns

Strategy: validation

Validate before calling

function assertNonHomeTarget(target) {
  const t = target.replace(/^~\/?/, '');
  if (t === '' ) throw new Error('source is required for the home directory itself; target a concrete file or subdir');
}

Try / catch

try {
  applyDotfiles();
} catch (e) {
  if (/source is required for the home directory itself/.test(e.message)) {
    console.error('Replace the ~ target with a concrete file or subdirectory entry');
  } else throw e;
}

Prevention

Never declare `~` itself as a dotfile target
Check template/glob output so dynamic targets can never collapse to `~`
Rely on implied source only for targets with at least one path segment under $HOME

When it happens

Trigger: Declaring `[dotfiles."~"]` (or an equivalent absolute $HOME path) with no `source`/`content`, reached via `validate_incoming_files`, `merge_file_entry`, or `source_is_implied` during dotfile expansion.

Common situations: Trying to manage $HOME wholesale as a single entry, a glob/template expanding to `~` itself, or a mistyped target like `~` instead of `~/.something`.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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