PRQL/prql · error

Could not parse PRQL version

Error message

Could not parse PRQL version {prql_version_override}\n{e}

What it means

compiler_version() reads the PRQL_VERSION_OVERRIDE env var and parses it as a semantic version to allow release tooling to override the reported compiler version. If the env var is set but is not a valid semver string, it panics with this message including the parse error. This is deliberately a hard failure so builds don't silently report a bogus version.

Solutions

  1. Set PRQL_VERSION_OVERRIDE to a valid semver string, e.g. 0.13.0 without a leading 'v'
  2. Unset the env var entirely (unset PRQL_VERSION_OVERRIDE) to fall back to git describe / cargo manifest version
  3. Check the CI/release script that exports the var and strip prefixes or suffixes before exporting
  4. Validate locally: parse the intended value with the semver crate or a semver linter before exporting

Example fix

// before
export PRQL_VERSION_OVERRIDE=v0.13.0
// after
export PRQL_VERSION_OVERRIDE=0.13.0
Defensive patterns

Strategy: validation

Validate before calling

# Validate the override before exporting
[[ "$PRQL_VERSION_OVERRIDE" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || unset PRQL_VERSION_OVERRIDE

Try / catch

// Not catchable (panic). Avoid by validating env var:
let override = std::env::var("PRQL_VERSION_OVERRIDE").ok();
if let Some(v) = override { if Version::parse(&v).is_err() { eprintln!("bad override"); } }

Prevention

When it happens

Trigger: Setting PRQL_VERSION_OVERRIDE to a value that fails Version::parse — e.g. missing patch segment ("v1.0" with the 'v', "1.2.3.4", non-numeric parts, trailing junk).

Common situations: CI release scripts exporting the var with a git tag like "v0.13.0" (leading 'v' is not semver), typos in the override, or a stale export in a shell profile.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of PRQL/prql@e164e249b9 (2026-09-09). Data as JSON: /api/errors/b4336144dfa8c462. Report an issue: GitHub.

Appendix: source

Thrown at prqlc/prqlc/src/lib.rs:145

pub(crate) mod utils;

pub type Result<T, E = Error> = core::result::Result<T, E>;

/// Get the version of the compiler. This is determined by the first of:
/// - An optional environment variable `PRQL_VERSION_OVERRIDE`; primarily useful
///   for internal testing.
///   - Note that this env var is checked on every call of this function.
///     Without checking each read, we found some internal tests were flaky. If
///     this caused any perf issues, we could adjust the tests that rely on
///     versions to run in a more encapsulated way (for example, use `prqlc`
///     binary tests, which we can guarantee won't have anything call this
///     before setting up the env var).
/// - The version returned by `git describe --tags`
/// - The version in the cargo manifest
pub fn compiler_version() -> Version {
    if let Ok(prql_version_override) = std::env::var("PRQL_VERSION_OVERRIDE") {
        return Version::parse(&prql_version_override).unwrap_or_else(|e| {
            panic!("Could not parse PRQL version {prql_version_override}\n{e}")
        });
    };

    static COMPILER_VERSION: OnceLock<Version> = OnceLock::new();
    COMPILER_VERSION
        .get_or_init(|| {
            let git_version = env!("VERGEN_GIT_DESCRIBE");
            let cargo_version = env!("CARGO_PKG_VERSION");
            Version::parse(git_version)
                .or_else(|e| {
                    log::info!("Could not parse git version number {git_version}\n{e}");
                    Version::parse(cargo_version)
                })
                .unwrap_or_else(|e| {
                    panic!("Could not parse prqlc version number {cargo_version}\n{e}")
                })
        })
        .clone()

View on GitHub (pinned to e164e249b9)