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

Total number of shards ({}) exceeds maximum allowed ({})

Error message

Total number of shards ({}) exceeds maximum allowed ({})

What it means

LocalNet::instantiate checks that num_initial_validators * num_shards stays within MAX_NUMBER_SHARDS (1000); beyond that the generated validator/shard topology would be invalid, so instantiation fails. Note the message prints num_shards, but the limit actually applies to the product validators times shards.

Source

Thrown at linera-service/src/cli_wrappers/local_net.rs:443

            self.namespace,
            self.num_initial_validators,
            self.num_proxies,
            self.num_shards,
            storage_config,
            self.cross_chain_config,
            self.path_provider,
            self.block_exporters,
            self.binary_dir,
            self.export_blocks_to_committee,
            self.block_export_transport,
        );
        let client = net.make_client().await;
        ensure!(
            self.num_initial_validators > 0,
            "There should be at least one initial validator"
        );
        let total_number_shards = self.num_initial_validators * self.num_shards;
        ensure!(
            total_number_shards <= MAX_NUMBER_SHARDS,
            "Total number of shards ({}) exceeds maximum allowed ({})",
            self.num_shards,
            MAX_NUMBER_SHARDS
        );
        net.generate_initial_validator_config().await?;
        client
            .create_genesis_config(
                self.num_other_initial_chains,
                self.initial_amount,
                self.policy_config,
                self.http_request_allow_list
                    .clone()
                    .or_else(|| Some(vec!["localhost".to_owned()])),
            )
            .await?;
        net.run().await?;
        Ok((net, client))

View on GitHub (pinned to 6c226ddcb3)

Solutions

1. Lower num_shards so validators x shards <= 1000 (e.g. 4 validators -> at most 250 shards each)
2. Reduce num_initial_validators
3. If genuinely needed, change MAX_NUMBER_SHARDS in your fork — but prefer smaller test topologies

Example fix

// before
builder.with_num_initial_validators(4).with_num_shards(300); // 4 * 300 = 1200 > 1000 -> error

// after
builder.with_num_initial_validators(4).with_num_shards(200); // 4 * 200 = 800 <= 1000

const MAX_NUMBER_SHARDS: usize = 1000;
let total = num_initial_validators * num_shards;
assert!(total <= MAX_NUMBER_SHARDS, "validators x shards = {total} exceeds {MAX_NUMBER_SHARDS}");

When it happens

Trigger: Configuring the LocalNet builder with shard counts such that validators x shards exceeds 1000, e.g. 4 validators with `.with_num_shards(300)` gives 1200 > 1000.

Common situations: Scaling stress tests beyond devnet-sized topologies; copying a topology constant from another test; forgetting that num_shards is per validator.

Related errors

• There should be at least one initial validator
• Failed to start node service
• Failed to start faucet
• Child process {self:?} already exited with status: {status}

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