linera-io/linera-protocol · error · ExecutionError

BytecodeTooLarge

BytecodeTooLarge

Error message

ExecutionError::BytecodeTooLarge

What it means

For bytecode blob types (ContractBytecode, ServiceBytecode, EvmBytecode), policy additionally checks the decompressed size: CompressedBytecode::decompressed_size_at_most fails with BytecodeTooLarge when the decompressed module would exceed maximum_bytecode_size (policy.rs:453), even if the compressed blob itself fits maximum_blob_size.

Source

Thrown at linera-execution/src/policy.rs:453

    }

    /// Returns how much fuel can be paid with the given balance.
    pub(crate) fn remaining_fuel(&self, balance: Amount, vm_runtime: VmRuntime) -> u64 {
        let fuel_unit = self.fuel_unit_price(vm_runtime);
        u64::try_from(balance.saturating_ratio(fuel_unit)).unwrap_or(u64::MAX)
    }

    /// Checks that the blob's size does not exceed the maximum allowed by this policy.
    pub fn check_blob_size(&self, content: &BlobContent) -> Result<(), ExecutionError> {
        ensure!(
            u64::try_from(content.bytes().len())
                .ok()
                .is_some_and(|size| size <= self.maximum_blob_size),
            ExecutionError::BlobTooLarge
        );
        match content.blob_type() {
            BlobType::ContractBytecode | BlobType::ServiceBytecode | BlobType::EvmBytecode => {
                ensure!(
                    CompressedBytecode::decompressed_size_at_most(
                        content.bytes(),
                        self.maximum_bytecode_size
                    )?,
                    ExecutionError::BytecodeTooLarge
                );
            }
            BlobType::Data
            | BlobType::ApplicationDescription
            | BlobType::ApplicationFormats
            | BlobType::Committee
            | BlobType::ChainDescription
            | BlobType::CheckpointExecutionState => {}
        }
        Ok(())
    }
}

View on GitHub (pinned to 6c226ddcb3)

Solutions

1. Optimize the build to shrink the decompressed module: run wasm-opt, raise opt-level, strip debug and custom sections
2. Split functionality into multiple smaller applications
3. Ensure the blob is actually compressed (publish CompressedBytecode, not raw module bytes)
4. If you operate the network, raise maximum_bytecode_size in the resource policy

Example fix

# before: publish raw module (decompressed size > maximum_bytecode_size)
cargo build --target wasm32-unknown-unknown
publish target/debug/myapp.wasm

# after: optimize then compress before publishing
wasm-opt -O3 target/debug/myapp.wasm -o myapp.opt.wasm
publish compress myapp.opt.wasm

// Validate the decompressed size against policy before publishing bytecode
let fits = CompressedBytecode::decompressed_size_at_most(
    bytecode.bytes(),
    policy.maximum_bytecode_size,
)?;
if !fits {
    return Err(anyhow!("decompressed bytecode exceeds maximum_bytecode_size"));
}
publish(bytecode)?;

fn is_bytecode_too_large(err: &ExecutionError) -> bool {
    matches!(err, ExecutionError::BytecodeTooLarge)
}

match publisher.publish_blob(bytecode_content).await {
    Ok(id) => id,
    Err(ref e) if is_bytecode_too_large(e) => {
        // deterministic: optimize or compress the module and republish
        return Err(anyhow!("bytecode too large after decompression; run wasm-opt and compress"));
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Publishing contract, service, or EVM bytecode whose decompressed module size exceeds the policy's maximum_bytecode_size, e.g. shipping an uncompressed or unoptimized Wasm module that is bigger than the limit once loaded.

Common situations: Unoptimized Wasm builds (debug symbols, no wasm-opt); a contract that grew past the limit after adding dependencies; networks that lowered maximum_bytecode_size; publishing raw bytes instead of a compressed bytecode container.

Related errors

• BlobTooLarge
• BlockTooLarge
• {}: {error}
• TooManyPublishedBlobs
• The function {0} is being called but is missing from the byt

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