astrid-runtime/astrid · error

release {resolved_ref} of {org}/{repo} ships no .capsule ass

Error message

release {resolved_ref} of {org}/{repo} ships no .capsule asset

What it means

When installing a capsule from a GitHub release with a pinned ref, the code first tries to download a prebuilt `.capsule` asset. If the ref resolved but the release ships no such asset, and the ref was pinned, it deliberately fails instead of silently falling back to building from HEAD — a pin must give you exactly that release, so the error is surfaced as actionable.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install.rs:375

                            .expect("non-empty candidates always select an index");
                        let (name, download_url) = &candidates[idx];
                        let id = download_and_unpack(&client, name, download_url, context).await?;
                        vec![id]
                    },
                    // Manual install with no `--capsule`: install EVERY capsule
                    // the release ships. Best-effort — report which assets fail
                    // but keep going, then fail if any did.
                    None => install_all_capsules(&client, &candidates, context).await?,
                };
                return Ok((ids, Some(resolved_ref)));
            }

            // The ref resolved, but the release ships no `.capsule` asset. A
            // pin must NOT silently fall through to building HEAD — fail with
            // the real, actionable cause. Unpinned, fall through to
            // clone-and-build.
            if pinned {
                bail!("release {resolved_ref} of {org}/{repo} ships no .capsule asset");
            }
        },
        // A pinned ref that could not be resolved is a hard error: surface
        // the real cause (a bad version/tag, a network failure) and never
        // build HEAD for a pin.
        Err(e) if pinned => {
            return Err(e).context(format!(
                "failed to resolve pinned version/tag for {org}/{repo}"
            ));
        },
        // Unpinned resolution failure (e.g. no `latest` release): fall
        // through to clone-and-build.
        Err(_) => {},
    }

    // Priority 2: clone + build from source via astrid-build — reached only
    // when nothing was pinned (a pin would have bailed above).
    let id = clone_and_build(url, repo, name_hint, context).await?;

View on GitHub (pinned to affd8760f4)

Solutions

  1. Check the release page for `org/repo` at `resolved_ref` — if assets were lost, re-run the release CI or upload the `.capsule` manually.
  2. Pin a different tag/ref that does ship a `.capsule` asset.
  3. If you accept building from source, install unpinned (or from the repo) instead of a pinned ref.
  4. Verify the project's release workflow still uploads `*.capsule` assets.

Example fix

// before
astrid capsule install gh:org/repo@v0.1.0   // release has no .capsule asset
// after
astrid capsule install gh:org/repo@v0.2.0   // pin a release that ships the asset
Defensive patterns

Strategy: validation

Validate before calling

// check the release ships a .capsule asset before pinning an install
// curl -s https://api.github.com/repos/ORG/REPO/releases/tags/TAG \
//   | jq -e '.assets[] | select(.name | endswith(".capsule"))' >/dev/null \
//   || echo "refusing to pin: no .capsule asset on this release"

Try / catch

match install_from_github(pin) {
    Err(e) if e.to_string().contains("ships no .capsule asset") => {
        eprintln!("Pinned release has no prebuilt capsule.");
        eprintln!("Pick another tag or install unpinned to build from source.");
    }
    other => other.expect("install failed"),
}

Prevention

When it happens

Trigger: `install_from_github` with a pinned `org/repo@ref` where the GitHub release exists but has no attached asset ending in `.capsule` (unpinned installs fall through to clone-and-build instead of erroring).

Common situations: Pinning a tag whose release was cut without the CI-generated `.capsule` artifact; CI asset upload failing or renamed; older releases predating the asset packaging step; pinning a source-only release.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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