linera-io/linera-protocol · error · async_graphql::Error

Storage error while reading chain description: {e}

Error message

Storage error while reading chain description: {e}

What it means

When an owner re-claims (duplicate `claim`), the faucet serves the stored chain by reading the ChainDescription blob directly: `storage.read_blob(BlobId::new(chain_id.0, BlobType::ChainDescription))`. This error wraps a failure returned by the storage backend itself; the underlying error is appended as `{e}` and logged as `Failed to read chain description blob for <chain>: <err>`. It means the backend (DynamoDB, ScyllaDB, Redis, service storage, ...) errored — not that the blob is merely absent.

Source

Thrown at linera-faucet/server/src/lib.rs:698

    chain_id: ChainId,
) -> Result<ChainDescription, Error>
where
    S: Storage,
{
    // Create blob ID from chain ID - the chain ID is the hash of the chain description blob
    let blob_id = BlobId::new(chain_id.0, BlobType::ChainDescription);

    // Read the blob directly from storage
    let blob = storage
        .read_blob(blob_id)
        .await
        .map_err(|e| {
            tracing::error!(
                "Failed to read chain description blob for {}: {}",
                chain_id,
                e
            );
            Error::new(format!(
                "Storage error while reading chain description: {e}"
            ))
        })?
        .ok_or_else(|| {
            tracing::error!("Chain description blob not found for chain {}", chain_id);
            Error::new(format!("Chain description not found for chain {chain_id}"))
        })?;

    // Deserialize the chain description from the blob bytes
    let description = bcs::from_bytes::<ChainDescription>(blob.bytes()).map_err(|e| {
        tracing::error!(
            "Failed to deserialize chain description for {}: {}",
            chain_id,
            e
        );
        Error::new(format!(
            "Invalid chain description data for chain {chain_id}"
        ))

View on GitHub (pinned to 6c226ddcb3)

Solutions

1. Read the appended `{e}` cause and the matching faucet log line to identify the backend error
2. Verify the storage backend the faucet was started with is reachable and its credentials are valid
3. Restart the faucet if the backend was restarted, so connections are re-established
4. Compare the current storage configuration with the one used when the chains were recorded — a different keyspace/table also surfaces here

Example fix

// before - surface the error directly
let chain = client.claim(owner, None).await?;

// after - retry transient backend failures with backoff
let chain = match client.claim(owner, None).await {
    Ok(chain) => chain,
    Err(e) if e.message.starts_with("Storage error while reading chain description") => {
        // inspect e.message suffix; retry only transient causes (timeouts, connection resets)
        retry_with_backoff(|| client.claim(owner, None), 3).await?
    }
    Err(e) => return Err(e),
};

fn is_storage_read_error(msg: &str) -> bool { msg.starts_with("Storage error while reading chain description") }

Catch the claim error; if the message starts with `Storage error while reading chain description`, inspect the appended cause. Retry transient causes (timeouts, connection resets) with exponential backoff and a small cap; treat auth/misconfiguration causes as permanent and alert the faucet operator.

When it happens

Trigger: A duplicate `claim(owner)` for an owner with an existing chain while the storage backend fails: connection refused, expired credentials, missing table/keyspace, timeouts, or I/O errors from the backend surfaced through `read_blob`.

Common situations: Faucet storage env vars (endpoint, credentials, region) wrong or stale after a redeploy; the database container being down or restarted; network partition between faucet and storage; local faucets pointed at a stopped Redis/ScyllaDB instance.

Related errors

• Chain description not found for chain {chain_id}
• Invalid chain description data for chain {chain_id}
• Failed to parse {spawn_mode_name} as a spawn_mode
• Failed to find address for {s}. {parse_error}
• Failed to find port for {s}. {parse_error}

AI-assisted analysis of linera-io/linera-protocol@6c226ddcb3 (2026-08-22). Data as JSON: /api/errors/37affbe019e0221c. Report an issue: GitHub.