jdx/mise · error

`--mode track` tracks a file where it is and takes no source

Error message

`--mode track` tracks a file where it is and takes no source; use `mise bootstrap dotfiles track <path>`

What it means

The dotfiles add command rejects `--mode track` because tracked-mode dotfiles are files kept in place at their real location, so they never have a source to copy from. The `add` subcommand only handles modes that copy or link from a source (e.g. copy, symlink), and track has its own dedicated `mise bootstrap dotfiles track <path>` subcommand. validate() bails immediately upon seeing mode "track" to redirect users to the correct command.

Source

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

impl DotfilesAdd {
    /// Validate and capture the requested targets as one transactional update.
    pub(crate) async fn run(self) -> Result<()> {
        let mode = self.validate()?;
        OperationScope::wrap("bootstrap dotfiles add", self.dry_run, self.run_inner(mode)).await
    }

    fn validate(&self) -> Result<FileMode> {
        if self.changed && !self.targets.is_empty() {
            bail!("--changed does not accept target arguments");
        }
        if !self.changed && self.targets.is_empty() {
            bail!("at least one target or --changed is required");
        }
        if self.source.is_some() && self.targets.len() != 1 {
            bail!("--source can only be used with one target");
        }
        match self.mode.as_deref() {
            Some("track") => bail!(
                "`--mode track` tracks a file where it is and takes no source; use `mise bootstrap dotfiles track <path>`"
            ),
            Some(mode) => {
                FileMode::parse(mode).ok_or_else(|| eyre::eyre!("unknown dotfile mode: {mode}"))
            }
            None => Ok(system::files::default_mode()),
        }
    }

    async fn run_inner(mut self, mode: FileMode) -> Result<()> {
        let config = Config::get().await?;
        let managed = system::files::files_from_config(&config)?;
        if self.changed {
            for req in &managed {
                if req.mode == FileMode::Copy
                    && req.target.is_file()
                    && !req.target.is_symlink()
                    && !req.source.is_dir()

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Run `mise bootstrap dotfiles track <path>` instead of `mise bootstrap dotfiles add <path> --mode track`.
2. If you actually want a copied/linked dotfile, use a supported mode such as `--mode copy` or `--mode symlink` and provide a source.
3. Remove `--source` if it was supplied; track takes no source.

Example fix

// before
mise bootstrap dotfiles add ~/.zshrc --mode track
// after
mise bootstrap dotfiles track ~/.zshrc

const MODES_WITH_SOURCE = new Set(['copy', 'symlink']);
if (mode === 'track') {
  // route to the dedicated subcommand instead
  throw new Error("use `mise bootstrap dotfiles track <path>` for track mode");
}

When it happens

Trigger: Running `mise bootstrap dotfiles add <target> --mode track` (with or without --source). validate() is called from run_inner during argument parsing, before any filesystem work, so the command always fails fast with this exact message.

Common situations: Users who know `track` is a valid FileMode from config files assume it is also valid for the add subcommand's --mode flag; scripts migrated from config-based dotfiles setup; users trying to add a file that already exists in place without a managed source.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• --changed does not accept target arguments
• at least one target or --changed is required
• --source can only be used with one target
• --changed requires trusted configuration: {}
• {target_raw}: target must be absolute or start with ~/

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