vectordotdev/vector · error

VRL version must be a stable semantic version

Error message

VRL version must be a stable semantic version

What it means

Same guard as the Vector version check, applied to the VRL version argument in `prepare::Cli::exec`: the pinned VRL version must be a stable semver release with no pre-release identifiers or build metadata.

Solutions

1. Pass a stable VRL release version, e.g. `vdev release prepare 0.46.0 0.12.0`.
2. Confirm the target VRL release exists on crates.io as a stable version before preparing.
3. If an RC pin is genuinely needed, do it outside the prepare command (it is rejected here by design).

Example fix

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

// check the VRL version is a stable crates.io release
const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(vrlVersion);
if (!stable) throw new Error(`VRL version must be stable: ${vrlVersion}`);

match prepare.exec() {
    Err(e) if e.to_string().contains("VRL version must be a stable") => {
        eprintln!("use a published stable VRL release version");
    }
    r => r?,
}

When it happens

Trigger: Running `vdev release prepare <vector-version> <vrl-version>` where the VRL version argument is a pre-release like `0.12.0-rc.1` or includes build metadata like `0.12.0+abc`.

Common situations: Pointing the release at a VRL RC to 'test' the pin, or copying a VRL version string from a development branch or git tag suffix.

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

• release version must be a stable semantic version
• Error running `git describe
• On latest release channel and tag
• --version has prerelease or build metadata; only plain…
• already exists

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

Appendix: source

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

}

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
            ),
            dry_run: self.dry_run,
        };

View on GitHub (pinned to bdb87aeaa4)