gitbutlerapp/gitbutler · error

Invalid version: {version}. Usage: but-installer [version|ni

Error message

Invalid version: {version}. Usage: but-installer [version|nightly]

What it means

Thrown by but-installer's Version::validate (crates/but-installer/src/config.rs:52) when the version argument starts with '-', i.e., it looks like a command-line flag (e.g., --help, -v) rather than a version. The validator rejects it because a leading dash would be ambiguous with flag parsing downstream; the usage hint in the message says the accepted forms are a plain version or `nightly`.

Source

Thrown at crates/but-installer/src/config.rs:52

    /// Create a new Version from a string, validating the format.
    ///
    /// # Errors
    /// Returns an error if the version string is invalid.
    pub fn new(version: String) -> Result<Self> {
        Self::validate(&version)?;
        Ok(Version(version))
    }

    /// Validate a version string format
    fn validate(version: &str) -> Result<()> {
        // Reject empty strings
        if version.is_empty() {
            bail!("Invalid version: empty string. Usage: but-installer [version|nightly]");
        }

        // Reject if it looks like a flag
        if version.starts_with('-') {
            bail!("Invalid version: {version}. Usage: but-installer [version|nightly]");
        }

        // Only allow semver-compatible characters
        if !version
            .chars()
            .all(|c| c.is_alphanumeric() || c == '.' || c == '-' || c == '+')
        {
            bail!(
                "Invalid version format: {version}. Version must contain only alphanumeric characters, dots, hyphens, and plus signs."
            );
        }

        // Must contain at least one alphanumeric character
        if !version.chars().any(|c| c.is_alphanumeric()) {
            bail!(
                "Invalid version format: {version}. Version must contain at least one alphanumeric character."
            );
        }

View on GitHub (pinned to caf1f223d3)

Solutions

  1. Remove the leading dash: pass `1.2.3` not `-1.2.3`
  2. If you wanted help, run the command without arguments or consult its docs — this installer accepts only a version or `nightly`
  3. Fix argument ordering in scripts so flags are not forwarded into the version position

Example fix

# before
but-installer -1.2.3   # rejected: looks like a flag

# after
but-installer 1.2.3
Defensive patterns

Strategy: validation

Validate before calling

let version = version.trim();
if version.starts_with('-') {
    eprintln!("'{version}' looks like a flag; expected a version like 1.2.3 or 'nightly'");
    std::process::exit(2);
}
let v = Version::new(version.to_string())?;

Type guard

fn looks_like_flag(v: &str) -> bool { v.starts_with('-') }

Try / catch

if let Err(err) = Version::new(version) {
    if err.to_string().contains("Usage: but-installer") { eprintln!("pass a plain version (1.2.3) or 'nightly', not flags"); std::process::exit(2); }
    return Err(err);
}

Prevention

When it happens

Trigger: Running `but-installer --help` or `but-installer -v` (the tool treats it as a version, not a flag); a script passing "$@" where the first extra token is a flag; negative-looking strings like "-1.2.3".

Common situations: Users trying to discover flags with --help; argument misordering in wrapper scripts; a version variable accidentally containing a leading dash.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/529bd92712ac2f89. Report an issue: GitHub.