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

Invalid chain description data for chain {chain_id}

Error message

Invalid chain description data for chain {chain_id}

What it means

The ChainDescription blob was found, but `bcs::from_bytes::<ChainDescription>(blob.bytes())` failed: the bytes stored at that blob ID are not a valid BCS-encoded ChainDescription. The faucet logs the underlying BCS error as `Failed to deserialize chain description for <chain>: <err>`. This points to corruption at rest or a serialization-format mismatch between writer and reader, not a network or availability problem.

Source

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

                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}"
        ))
    })?;

    Ok(description)
}

impl<C> BatchProcessor<C>
where
    C: ClientContext + 'static,
{
    /// Creates a new batch processor.
    fn new(
        config: BatchProcessorConfig,
        context: Arc<Mutex<C>>,
        client: ChainClient<C::Environment>,
        faucet_storage: Arc<FaucetDatabase>,
        pending_requests: Arc<Mutex<VecDeque<PendingRequest>>>,

View on GitHub (pinned to 6c226ddcb3)

Solutions

1. Check the faucet log for the exact BCS error to distinguish truncation from a type/layout mismatch
2. Ensure faucet, wallet, and node run the same Linera version (verify via the `version` query) so writers and readers agree on the format
3. If the blob is genuinely corrupt, remove the stale owner mapping or reset the faucet's records so owners can re-claim, or restore the blob from a known-good backup
4. Reproduce against a copy of the storage before deleting anything

fn is_invalid_chain_description(msg: &str) -> bool { msg.starts_with("Invalid chain description data for chain") }

Catch the claim error; on `Invalid chain description data for chain <id>`, do not retry — the stored blob cannot be decoded. Capture the chain ID and the faucet's `version` and escalate to the operator; the fix is restoring/removing the corrupt blob or realigning versions server-side.

When it happens

Trigger: Storage-level corruption of the blob bytes; a blob written by an incompatible Linera version whose ChainDescription BCS layout changed; a wrong-type or manually injected blob occupying that BlobId; truncated writes from an unclean shutdown.

Common situations: Upgrading faucet/wallet across protocol versions with old blobs still in storage; restoring blobs from a different network or epoch; buggy migration scripts or manual tampering writing blobs under computed IDs; disk-level corruption.

Related errors

• bcs: {e}
• empty
• Storage error while reading chain description: {e}
• Chain description not found for chain {chain_id}
• Failed to parse {spawn_mode_name} as a spawn_mode

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