firecracker-microvm/firecracker · error · ValueError

version does not match vX.Y.Z

Error message

version does not match vX.Y.Z

What it means

tools/gh_release.py registers `version` as the argparse `type` for the required `--version` flag. The function runs `re.fullmatch(r"v\d+\.\d+\.\d+", version_str)` and raises ValueError when the string is not exactly a semantic version prefixed with a lowercase 'v'. argparse catches this ValueError and re-emits it as a usage error (`argument --version: invalid version value: ...`), aborting the draft-release/upload workflow before any asset is uploaded.

Source

Thrown at tools/gh_release.py:99

    # Upload assets
    for asset in assets:
        content_type = "application/octet-stream"
        if asset.suffix == ".txt":
            content_type = "text/plain"
        elif asset.suffix in {".tgz", ".gz"}:
            content_type = "application/gzip"
        print(f"Uploading asset {asset} with content-type={content_type}")
        gh_release.upload_asset(str(asset), label=asset.name, content_type=content_type)

    release_url = gh_release.html_url
    print(f"Draft release created successful. Check it out at {release_url}")


def version(version_str: str):
    """Validate version parameter"""
    if not re.fullmatch(r"v\d+\.\d+\.\d+", version_str):
        raise ValueError("version does not match vX.Y.Z")
    return version_str


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--version",
        required=True,
        metavar="vX.Y.Z",
        help="Firecracker version.",
        type=version,
    )
    parser.add_argument(
        "--repository", required=False, default="firecracker-microvm/firecracker"
    )
    parser.add_argument("--github-token", required=True)
    args = parser.parse_args()
    github_release(

View on GitHub (pinned to ea50487ec1)

Solutions

1. Pass the version in exact tag form with the leading lowercase v: `python3 tools/gh_release.py --version v1.10.0`.
2. Strip pre-release/build metadata before invoking: use the released tag (e.g. v1.10.0) instead of v1.10.0-rc1.
3. If you drive this from CI, derive the argument from the git tag itself (`git describe --tags --exact-match`) so the format always matches, or add `v${VERSION}` formatting in the pipeline.
4. Only as a last resort, extend the regex in tools/gh_release.py (e.g. allow `-rc\d+`) if your project genuinely releases pre-release versions through this tool.

Example fix

# before
python3 tools/gh_release.py --version 1.10.0   # ValueError: version does not match vX.Y.Z

# after
python3 tools/gh_release.py --version v1.10.0

import re, subprocess, sys

version = os.environ["RELEASE_VERSION"]  # however you obtain it
if not re.fullmatch(r"v\d+\.\d+\.\d+", version):
    tag = subprocess.run(["git", "describe", "--tags", "--exact-match"],
                         capture_output=True, text=True).stdout.strip()
    version = tag if re.fullmatch(r"v\d+\.\d+\.\d+", tag) else f"v{version.lstrip('v')}"
subprocess.run([sys.executable, "tools/gh_release.py", "--version", version])

def is_release_tag(s: str) -> bool:
    """True when s is exactly the vX.Y.Z form gh_release.py accepts."""
    return re.fullmatch(r"v\d+\.\d+\.\d+", s) is not None

# argparse converts the ValueError into a usage error and exits(2); catch SystemExit if wrapping the CLI
try:
    tools.gh_release.main(["--version", version])
except SystemExit as e:
    print(f"release aborted (bad --version): {version!r}", file=sys.stderr)
    raise

When it happens

Trigger: Calling `python3 tools/gh_release.py --version 1.10.0` (missing the leading 'v'), `--version v1.10` (only two components), `--version v1.10.0-rc1` or `--version v1.10.0^` (pre-release/build suffixes rejected by fullmatch), or `--version V1.10.0` (uppercase V). Any of these makes the release tool exit during argument parsing.

Common situations: Release scripts that interpolate a git tag or CARGO_PKG_VERSION into `--version`; git tags carrying an annotated suffix; CI passing the version from a variable that was normalized without the 'v'. The regex demands the literal tag format `vX.Y.Z`, which is stricter than plain semver.

Related errors

• {p} not found in container and not under host workspace {hos
• No kernel found and --kernel was not provided.
• No rootfs found and --rootfs was not provided.

AI-assisted analysis of firecracker-microvm/firecracker@ea50487ec1 (2026-08-16). Data as JSON: /api/errors/969886b1e019e097. Report an issue: GitHub.