risingwavelabs/risingwave · error · SinkError::Config

`num_shards` must be greater than 0

Error message

`num_shards` must be greater than 0

What it means

Validation guard in TurbopufferConfig::from_btreemap that rejects sink properties where num_shards is 0. The sink must write into at least one Turbopuffer shard; a zero value cannot be mapped to a valid namespace layout, so sink creation fails immediately with a config error.

Solutions

  1. Set num_shards to a positive integer
  2. Remove num_shards to let the sink decide default sharding
  3. Validate the value before creating the sink

Example fix

// before
WITH (connector='turbopuffer', num_shards = '0')
// after
WITH (connector='turbopuffer', num_shards = '4')
Defensive patterns

Strategy: validation

Validate before calling

if (props.num_shards !== undefined && Number(props.num_shards) <= 0) throw new Error('num_shards must be > 0')

Type guard

const validShards = (n) => Number.isInteger(n) && n > 0;

Try / catch

catch (SinkError::Config(e)) if e.contains('num_shards') { set positive shard count and retry }

Prevention

When it happens

Trigger: CREATE SINK with connector='turbopuffer' and WITH option num_shards = '0'.

Common situations: Placeholder 0 left in config; misunderstanding that omitting the option means unlimited/zero shards.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/774548162c8acda4. Report an issue: GitHub.

Appendix: source

Thrown at src/connector/src/sink/turbopuffer.rs:112

impl TurbopufferConfig {
    fn from_btreemap(values: BTreeMap<String, String>) -> Result<Self> {
        let config = serde_json::from_value::<TurbopufferConfig>(
            serde_json::to_value(values).expect("serialize sink properties"),
        )
        .map_err(|e| SinkError::Config(anyhow!(e)))?;
        if config.write_batch_size == 0 {
            return Err(SinkError::Config(anyhow!(
                "`write_batch_size` must be greater than 0"
            )));
        }
        if config.max_linger_second == 0 {
            return Err(SinkError::Config(anyhow!(
                "`max_linger_second` must be greater than 0"
            )));
        }
        if config.num_shards == Some(0) {
            return Err(SinkError::Config(anyhow!(
                "`num_shards` must be greater than 0"
            )));
        }
        Ok(config)
    }
}

#[derive(Clone, Debug)]
enum TurbopufferNamespace {
    Static(String),
    Dynamic { index: usize },
}

#[derive(Clone, Debug)]
pub struct TurbopufferSink {
    config: TurbopufferConfig,
    schema: Schema,
    pk_index: usize,

View on GitHub (pinned to 6469eb736d)