vectordotdev/vector · error

--version has prerelease or build metadata; only plain…

Error message

--version {v} has prerelease or build metadata; only plain X.Y.Z is allowed

What it means

Thrown by `cargo vdev deprecation enact` when --version is given as a semver with prerelease (e.g. -alpha) or build metadata. Only a plain release-shaped X.Y.Z version is a valid removal target for a deprecation.

Solutions

1. Pass a plain X.Y.Z version: `cargo vdev deprecation enact <slug> --version 0.58.0`.
2. Strip prerelease/build metadata from the version string before invoking.
3. Omit --version entirely to let the command compute the next release from git::latest_release_version.
4. Validate your version input with a semver parser that rejects pre/build parts before calling.

Example fix

// before
--version 0.58.0-alpha.1
// after
--version 0.58.0

let v: Version = version_str.parse()?;
if !v.pre.is_empty() || !v.build.is_empty() { eprintln!("use plain X.Y.Z, got {version_str}"); return; }

fn is_plain_release(v: &Version) -> bool { v.pre.is_empty() && v.build.is_empty() }

match result { Err(e) if e.to_string().contains("prerelease or build metadata") => { eprintln!("Strip suffixes: 0.58.0-alpha -> 0.58.0"); } Err(e) => return Err(e), Ok(v) => v }

When it happens

Trigger: Running enact with `--version 0.58.0-alpha`, `--version 1.2.3+build.5`, etc. — v.pre or v.build is non-empty after parsing the Version.

Common situations: Copy-pasting a full semver from git tags or cargo output that includes prerelease/build suffixes, or scripting enact from a version string that was not normalized.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• expected a deprecation slug (e.g…
• Neither nor found; the deprecation fragment system is not…
• No deprecation fragment found at
• release version must be a stable semantic version
• VRL version must be a stable semantic version

AI-assisted analysis of vectordotdev/vector@bdb87aeaa4 (2026-09-16). Data as JSON: /api/errors/e0b0de052693a804. Report an issue: GitHub.

Appendix: source

Thrown at vdev/src/commands/deprecation/enact.rs:53

        let filename = format!("{stem}.md");

        let path = dir.join(&filename);
        if !path.exists() {
            bail!("No deprecation fragment found at {}", path.display());
        }

        // Parse the fragment to get entry data.
        let entries = deprecation::read_deprecation_fragments(&dir)?;
        let entry = entries
            .into_iter()
            .find(|e| e.filename == filename)
            .ok_or_else(|| anyhow::anyhow!("Could not parse {filename}"))?;

        let version = if let Some(v) = self.version {
            // Reject `--version 0.58.0-alpha` and friends: only release-shaped
            // semver is valid here.
            if !v.pre.is_empty() || !v.build.is_empty() {
                bail!(
                    "--version {v} has prerelease or build metadata; only plain X.Y.Z is allowed"
                );
            }
            v
        } else {
            let latest = git::latest_release_version()?;
            Version::new(latest.major, latest.minor + 1, 0)
        };

        if !deprecation::later_minor(&version, &entry.deprecated_since.0) {
            bail!(
                "removed_in ({version}) must be in a later minor release than deprecated_since ({}); \
                 the deprecation policy requires at least one minor release between \
                 the announcement and removal. \
                 Check --version or the fragment's `deprecated_since` field.",
                entry.deprecated_since
            );
        }

View on GitHub (pinned to bdb87aeaa4)