jdx/mise · error

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

Error message

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

What it means

`--mode track` tells mise to track a dotfile where it currently lives, without moving or linking it, so it inherently cannot take a `--source`. validate() rejects `--mode track` combined with `--source` and points the user to the dedicated `mise dot track` command.

Solutions

1. Use `mise dot track <path>` instead, which is the dedicated command for tracking in place.
2. Or remove `--source` if the goal was `mise dotfiles add --mode track <path>`.
3. Use `--mode link` (or the default mode) with --source if you actually want a sourced/moved file.

Example fix

// before
$ mise dotfiles add --mode track --source ~/dotfiles/zshrc ~/.zshrc

// after
$ mise dot track ~/.zshrc

# guard: never combine --mode track with --source
if [ "$MODE" = "track" ] && [ -n "$SOURCE" ]; then
  echo "--mode track takes no --source; use 'mise dot track <path>'" >&2; exit 2
fi

When it happens

Trigger: Running `mise dotfiles add --mode track --source <path> <target>` — the mode string equals "track" in validate()'s match arm.

Common situations: Copy-pasting an add command and swapping the mode without removing --source; confusion between the `add --mode track` and `dot track` subcommands.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• --changed does not accept target arguments
• --source can only be used with one target
• a repository preview directory requires a dry run
• `--all` needs `--to
• at least one target or --changed is required

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

Appendix: source

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

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 dot 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 secrets = system::secrets::resolve(&config, self.prompt_secrets)?;
        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()

View on GitHub (pinned to 533346cc37)