neondatabase/neon · error

{n} shards but no stripe_size

Error message

{n} shards but no stripe_size

What it means

PageserverConnectionInfo::from_connstr treats each comma-separated connection string as one shard. When more than one is present (n > 1), the system is sharded, and a ShardStripeSize must accompany the shard count to distribute keys across shards. Passing no stripe_size in the multi-shard case is a spec inconsistency and bails immediately.

Source

Thrown at libs/compute_api/src/spec.rs:293

        match shard_infos.len() {
            0 => anyhow::bail!("empty connection string"),
            1 => {
                // We assume that if there's only connection string, it means "unsharded",
                // rather than a sharded system with just a single shard. The latter is
                // possible in principle, but we never do it.
                let shard_count = ShardCount::unsharded();
                let only_shard = shard_infos.first().unwrap().clone();
                let shards = vec![(ShardIndex::unsharded(), only_shard)];
                Ok(PageserverConnectionInfo {
                    shard_count,
                    stripe_size: None,
                    shards: shards.into_iter().collect(),
                    prefer_protocol: PageserverProtocol::Libpq,
                })
            }
            n => {
                if stripe_size.is_none() {
                    anyhow::bail!("{n} shards but no stripe_size");
                }
                let shard_count = ShardCount(n.try_into()?);
                let shards = shard_infos
                    .into_iter()
                    .enumerate()
                    .map(|(idx, shard_info)| {
                        (
                            ShardIndex {
                                shard_count,
                                shard_number: ShardNumber(
                                    idx.try_into().expect("shard number fits in u8"),
                                ),
                            },
                            shard_info,
                        )
                    })
                    .collect();
                Ok(PageserverConnectionInfo {

View on GitHub (pinned to 8f60b04da4)

Solutions

1. Supply the stripe_size argument (e.g. from the spec's stripe size field, default 32768) when parsing a multi-shard connstr
2. Migrate the spec to the pageserver_connection_info field, which carries stripe_size per spec
3. If the deployment is really unsharded, remove the comma / extra connection strings so exactly one remains

Example fix

// before
let info = PageserverConnectionInfo::from_connstr(connstr, None)?;
// after
let stripe = spec.stripe_size.map(ShardStripeSize)
    .unwrap_or(ShardStripeSize::new(32768).unwrap());
let info = PageserverConnectionInfo::from_connstr(connstr, Some(stripe))?

let n_shards = connstr.split(',').count();
anyhow::ensure!(n_shards == 1 || stripe_size.is_some(),
    "{n_shards} shard connection strings require a stripe_size");
let info = PageserverConnectionInfo::from_connstr(connstr, stripe_size)?;

fn shard_config_is_consistent(connstr: &str, stripe_size: Option<ShardStripeSize>) -> bool {
    let n = connstr.split(',').count();
    n == 1 || stripe_size.is_some()
}

When it happens

Trigger: Calling from_connstr with a connstr containing commas (multiple shard connection strings) while stripe_size is None — e.g. a legacy sharded ComputeSpec or neon.pageserver_connstring GUC set to several URLs without the accompanying stripe-size configuration.

Common situations: Upgrading a sharded deployment that still uses the legacy pageserver_connstring field; copy-pasting multi-shard connstrs without the stripe size parameter; partial migration to pageserver_connection_info where stripe size was dropped.

Related errors

• empty connection string
• shard connection info missing for shard {}
• must have at least one pageserver
• shard {shard_index} missing from pageserver_connection_info
• invalid compute claims scope "{s}"

AI-assisted analysis of neondatabase/neon@8f60b04da4 (2026-08-16). Data as JSON: /api/errors/8f58e7ab782ca822. Report an issue: GitHub.