astrid-runtime/astrid · error

capsule ' ': version must not contain surrounding whitespace

Error message

capsule '{}': version must not contain surrounding whitespace

What it means

Capsule versions must be clean, so validate_manifest compares the raw `cap.version` against its trimmed form and bails when they differ (leading/trailing whitespace). Whitespace-padded versions would produce surprising semver parse results or mismatched resolution keys downstream.

Solutions

  1. Strip surrounding whitespace from the `version` value in the manifest.
  2. Enable trim-on-save / trailing-whitespace highlighting in your editor for manifest files.
  3. If the manifest is generated, trim the version string at generation time.

Example fix

# before
[[capsules]]
name = "http"
version = " 1.2.0 "

# after
[[capsules]]
name = "http"
version = "1.2.0"
Defensive patterns

Strategy: validation

Validate before calling

for cap in &manifest.capsules {
    if cap.version != cap.version.trim() {
        panic!("capsule '{}': trim version whitespace", cap.name);
    }
}

Try / catch

if let Err(e) = validate_manifest(&manifest) {
    if e.to_string().contains("surrounding whitespace") {
        eprintln!("strip padding from version: {e}");
    }
}

Prevention

When it happens

Trigger: A `[[capsules]]` entry with `version = " 1.2.0 "` or `"1.2.0\n"` — any leading/trailing space, tab, or newline in the version string.

Common situations: Hand-editing manifests where editors leave trailing spaces; copy-pasting a version from a webpage or terminal with trailing whitespace; YAML/TOML string values that preserved padding.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/f304f2c2a15d6db6. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/distro/validate.rs:157

            anyhow::bail!("duplicate capsule name '{}'", cap.name);
        }
        // Distros compose *released* capsules. `branch`/`rev` selectors
        // can only be honored by compiling from a git ref — the exact
        // toolchain dependency offline/headless distro seeding exists to
        // remove. Reject them: a distro must pin a released `version` or
        // `tag`. (Git-ref installs remain available via the standalone
        // `astrid capsule install` command.)
        if cap.branch.is_some() || cap.rev.is_some() {
            anyhow::bail!(
                "capsule '{}': branch/rev require building from source and are not allowed in a \
                 distro manifest — pin a released `version` or `tag` (git-ref installs are \
                 available via `astrid capsule install`).",
                cap.name,
            );
        }
        let version = cap.version.trim();
        if cap.version != version {
            anyhow::bail!(
                "capsule '{}': version must not contain surrounding whitespace",
                cap.name
            );
        }
        if !version.is_empty() && Version::parse(version).is_err() {
            anyhow::bail!(
                "capsule '{}': version '{}' is not valid semver",
                cap.name,
                cap.version
            );
        }
        let tag = cap.tag.as_deref().map(str::trim);
        if let Some(raw_tag) = cap.tag.as_deref()
            && raw_tag != raw_tag.trim()
        {
            anyhow::bail!(
                "capsule '{}': tag must not contain surrounding whitespace",
                cap.name

View on GitHub (pinned to affd8760f4)