Cannot change version of existing tool stub from {} to {}

Error message

Cannot change version of existing tool stub from {} to {}

What it means

`mise generate tool-stub` is append/extend-only for existing stub files: when the output file already exists and contains a `version` key, regenerating with a different --version is rejected. The tool reuses the existing TOML document so platform URLs can be added incrementally; changing the version would silently re-point every existing platform URL/checksum to the wrong release.

Source

Thrown at src/cli/generate/tool_stub.rs:267

            bail!("Either --url or --platform-url must be specified");
        }

        // Read existing file if it exists
        let (existing_content, mut doc) = if self.output.exists() {
            let content = file::read_to_string(&self.output)?;
            let toml_content = extract_toml_from_stub(&content);

            let document = toml_content.parse::<DocumentMut>()?;
            (Some(content), document)
        } else {
            (None, DocumentMut::new())
        };

        // If file exists but we're trying to set a different version, bail
        if existing_content.is_some() && doc.get("version").is_some() {
            let existing_version = doc.get("version").and_then(|v| v.as_str()).unwrap_or("");
            if existing_version != self.version {
                bail!(
                    "Cannot change version of existing tool stub from {} to {}",
                    existing_version,
                    self.version
                );
            }
        }

        // Set or update version only if it's not "latest" (which should be the default)
        if self.version != "latest" {
            doc["version"] = toml_edit::value(&self.version);
        }

        // Get the stub filename (without path)
        let stub_filename = self
            .output
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("");

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Regenerate from scratch: delete (or rename) the existing stub file and run generate again with the new --version
Edit the stub file by hand and change the `version` line, then run `mise generate tool-stub <file> --lock` or `--fetch` to refresh checksums/URLs
Write the new version to a different output path and keep both stubs

Example fix

# before (stub file has version = "1.0.0")
mise generate tool-stub ./ctl --version 2.0.0 --url https://.../v2.0.0/ctl.tar.gz
# after
rm ./ctl && mise generate tool-stub ./ctl --version 2.0.0 --url https://.../v2.0.0/ctl.tar.gz

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
stub=./ctl
if [[ -f "$stub" ]]; then
  cur=$(grep -oP '^version\s*=\s*"\K[^"]+' "$stub")
  if [[ "$cur" && "$cur" != "$NEW_VER" ]]; then
    echo "stub is version $cur; removing before regenerating at $NEW_VER" >&2
    rm "$stub"
  fi
fi
mise generate tool-stub "$stub" --version "$NEW_VER" --url "$url"

Try / catch

if ! mise generate tool-stub ./ctl --version "$v" ... 2>err.log; then grep -q 'Cannot change version' err.log && { rm ./ctl; mise generate tool-stub ./ctl --version "$v" ...; }; fi

Prevention

Treat stub version as immutable per file; delete or rename the stub when bumping versions
In release automation, generate to a fresh path per release tag

When it happens

Trigger: Running generate a second time on the same output file with `--version 2.0.0` when the stub already says `version = "1.0.0"`; CI pipelines that pass a bumped version variable into a stub file kept in the repo.

Common situations: Maintaining a checked-in stub across releases; incrementally adding platforms with `--platform-url` (works fine) but also bumping --version in the same invocation (fails).

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/68c559d4b896c4a5. Report an issue: GitHub.