astrid-runtime/astrid · error

describe WASM in system catalog

Error message

describe WASM in system catalog

What it means

Wraps a storage error from content().describe() when read_catalog_wasm looks up a content-addressed WASM entry (bin/{hash}.wasm) in the system catalog. A descriptor lookup that errors (as opposed to returning None) means the catalog backend itself failed, not that the entry is absent — absence yields the separate 'catalog entry is missing' error.

Source

Thrown at crates/astrid-capsule-install/src/wasm.rs:115

                },
            }
        }
    }

    Ok(Some(WasmAddressed { hash, bytes }))
}

/// Read one verified executable from the system-owned content catalog.
pub(crate) fn read_catalog_wasm(
    storage: &RuntimePrincipalStore,
    hash: &str,
) -> anyhow::Result<Vec<u8>> {
    let name = ContentName::new(format!("bin/{hash}.wasm"))
        .context("construct system WASM catalog name")?;
    let descriptor = storage
        .content()
        .describe(&StateOwner::System, &name)
        .map_err(|error| anyhow::anyhow!(error))
        .context("describe WASM in system catalog")?
        .ok_or_else(|| anyhow::anyhow!("WASM catalog entry is missing: bin/{hash}.wasm"))?;
    storage
        .content()
        .read_range(&StateOwner::System, &name, 0, descriptor.logical_bytes())
        .map_err(|error| anyhow::anyhow!(error))
        .context("read WASM from system catalog")?
        .ok_or_else(|| anyhow::anyhow!("WASM catalog entry has no readable bytes: bin/{hash}.wasm"))
}

/// Verify that the system catalog entry for `expected` exists and hashes to
/// its content-addressed name.
pub fn catalog_wasm_hash(
    storage: &RuntimePrincipalStore,
    expected: &str,
) -> anyhow::Result<String> {
    let actual = blake3::hash(&read_catalog_wasm(storage, expected)?)
        .to_hex()

View on GitHub (pinned to affd8760f4)

Solutions

1. Read the wrapped source error in the anyhow chain for the actual backend failure
2. Check filesystem permissions and health of the system content catalog directory
3. If a storage-version upgrade happened, re-publish the WASM (install again) so catalog metadata is regenerated
4. Retry after confirming the store backend is up

// probe catalog health before reads
storage.content().describe(&StateOwner::System, &probe_name)
    .map_err(|e| format!("catalog backend unhealthy: {e}"))?;

match catalog_wasm_hash(&storage, &expected) {
    Err(e) if e.chain().any(|c| c.to_string().contains("describe WASM in system catalog")) => {
        // backend failure, not a missing entry: surface the source error and retry after repair
        repair_catalog_index()?;
        catalog_wasm_hash(&storage, &expected)
    }
    other => other,
}

When it happens

Trigger: catalog_wasm_hash -> read_catalog_wasm calls storage.content().describe(&StateOwner::System, &name) and the call returns Err, converted via map_err + context.

Common situations: Corrupted or locked content-store index; permission errors reading catalog metadata; storage backend outage; mismatched storage version after an upgrade migrating catalog formats.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• publish WASM into the system content catalog
• WASM catalog entry is missing: bin/{hash}.wasm
• read WASM from system catalog
• WASM catalog entry has no readable bytes: bin/{hash}.wasm
• WASM capsule has no BLAKE3 hash in meta.json

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