vectordotdev/vector · error

release version must be a stable semantic version

Error message

release version must be a stable semantic version

What it means

`prepare::Cli::exec` refuses to run the release-preparation flow when the supplied Vector release version is a pre-release (has pre-release identifiers) or carries build metadata. Releases must be stable semver versions like 0.46.0, not 0.46.0-rc.1.

Solutions

1. Pass a stable semver version without pre-release/build parts, e.g. `vdev release prepare 0.46.0 0.12.0`.
2. If you intended to release an RC, this command does not support it — use the appropriate pre-release workflow instead.
3. Verify the version with a semver check before invoking: strip `-...` and `+...` components.

Example fix

// before
$ vdev release prepare 0.46.0-rc.1 0.12.0
release version must be a stable semantic version
// after
$ vdev release prepare 0.46.0 0.12.0

// ensure a stable semver before calling prepare
function isStable(v) { return /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(v); }
if (!isStable(versionArg)) throw new Error(`prepare needs a stable version, got ${versionArg}`);

if let Err(e) = prepare.exec() {
    if e.to_string().contains("stable semantic version") {
        eprintln!("strip -prerelease/+build from the version argument and retry");
    }
}

When it happens

Trigger: Running `vdev release prepare <version> <vrl-version>` where the Vector version argument contains a `-pre` suffix or `+build` metadata (e.g. `0.46.0-rc.1`).

Common situations: Practicing the release process with an RC version, accidentally pasting a version string from a pre-release tag, or scripting prepare with `$(git describe)` output that appends metadata.

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

• VRL version must be a stable semantic version
• Error running `git describe
• Failed to find validation configuration from given test…
• invalid slug ' ': only ASCII letters, digits, '_', and '-'…
• On latest release channel and tag

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

Appendix: source

Thrown at vdev/src/commands/release/prepare.rs:46

    /// Dry run. Enabling this will make it so no PRs will be created and no branches will be pushed upstream.
    #[arg(long, default_value_t = false)]
    dry_run: bool,
}

struct Prepare {
    new_vector_version: Version,
    vrl_version: Version,
    repo_root: PathBuf,
    latest_vector_version: Version,
    release_branch: String,
    release_preparation_branch: String,
    dry_run: bool,
}

impl Cli {
    pub fn exec(self) -> Result<()> {
        if !self.version.pre.is_empty() || !self.version.build.is_empty() {
            bail!("release version must be a stable semantic version");
        }
        if !self.vrl_version.pre.is_empty() || !self.vrl_version.build.is_empty() {
            bail!("VRL version must be a stable semantic version");
        }
        let repo_root = paths::find_repo_root()?;
        env::set_current_dir(&repo_root)?;

        let prepare = Prepare {
            new_vector_version: self.version.clone(),
            vrl_version: self.vrl_version,
            repo_root,
            latest_vector_version: git::latest_release_version()?,
            release_branch: format!("v{}.{}", self.version.major, self.version.minor),
            // Websites containing `website` will also generate website previews.
            // Caveat is these branches can only contain alphanumeric chars and dashes.
            release_preparation_branch: format!(
                "prepare-v-{}-{}-{}-website",
                self.version.major, self.version.minor, self.version.patch

View on GitHub (pinned to bdb87aeaa4)