What causes "invalid version requirement `{v}`" in FuelLabs/sway?

Use a valid semver requirement: forc add pkg@1.2.3, pkg@^1.2.0, or pkg@>=0.5,<0.9.

invalid version requirement `{v}`

Error message

invalid version requirement `{v}`

What it means

When a forc add spec contains '@', the part after it is parsed with semver::VersionReq::parse - the cargo-style requirement grammar ('1.2.3', '^1.2', '>=0.5, <0.9'). This error echoes the exact string that failed to parse. Version tags with 'v' prefixes, branch names, or words like 'latest' are not semver requirements and are rejected here.

Source

Thrown at forc-pkg/src/manifest/dep_modifier.rs:259

impl FromStr for DepSpec {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> anyhow::Result<Self> {
        if s.trim().is_empty() {
            bail!("Dependency spec cannot be empty");
        }

        let mut s = s.trim().split('@');

        let name = s
            .next()
            .ok_or_else(|| anyhow::anyhow!("missing dependency name"))?;

        let version_req = s.next().map(|s| s.to_string());

        if let Some(ref v) = version_req {
            semver::VersionReq::parse(v)
                .map_err(|_| anyhow::anyhow!("invalid version requirement `{v}`"))?;
        }

        Ok(Self {
            name: name.to_string(),
            version_req,
        })
    }
}

impl fmt::Display for DepSpec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.version_req {
            Some(version) => write!(f, "{}@{}", self.name, version),
            None => write!(f, "{}", self.name),
        }
    }
}

View on GitHub (pinned to 47e5e902fa)

Solutions

Use a valid semver requirement: forc add pkg@1.2.3, pkg@^1.2.0, or pkg@>=0.5,<0.9.
To depend on a git branch, tag or commit, edit Forc.toml's [dependencies] with git = ..., and branch = .../tag = ... keys rather than a version spec.
Validate the requirement string against the semver spec (semver.org) or with cargo's own parser before scripting many adds.

Example fix

# before
$ forc add mydep@v1.2.3

# after
$ forc add mydep@1.2.3

# or pin a git tag in Forc.toml
[dependencies]
mydep = { git = "https://github.com/org/mydep", tag = "v1.2.3" }

Defensive patterns

Strategy: validation

Validate before calling

// Rust, validate the version-req half before calling DepSpec::from_str / forc add:
fn valid_version_req(spec: &str) -> bool {
    match spec.trim().split_once('@') {
        Some((_, v)) => semver::VersionReq::parse(v).is_ok(),
        None => true, // no version part is fine
    }
}

Try / catch

// anyhow Result - convert to an actionable message:
match DepSpec::from_str("pkg@latest") {
    Err(e) if e.to_string().contains("invalid version requirement") =>
        eprintln!("use a semver requirement like ^1.2.0, or a git/branch entry in Forc.toml"),
    other => other.unwrap(),
}

Prevention

Use cargo-style semver requirements after @ (^1.2.0, >=0.5,<0.9, 1.2.3).
Never use 'latest', 'v'-prefixed tags, or branch names as version requirements.
Put branch/tag/commit dependencies in Forc.toml with git keys instead.
For git-tag pins like v1.2.3, declare tag = "v1.2.3" rather than @v1.2.3.

When it happens

Trigger: forc add pkg@latest, pkg@v1.0.0, pkg@main, or any post-@ string that is not a valid semver requirement range.

Common situations: Habits carried from npm ('latest') or git tags ('v1.0.0'); wanting to depend on a branch or commit instead of a version; typos like '1..2'.

Related errors

AI-assisted analysis of FuelLabs/sway@47e5e902fa (2026-08-16). Data as JSON: /api/errors/7237c8bfc3bc6aac. Report an issue: GitHub.