risingwavelabs/risingwave · error · SinkError

Cannot find `{KEY_FORMAT}`,please set it.

Error message

Cannot find `{KEY_FORMAT}`,please set it.

What it means

For `redis_value_type = 'geospatial'` sinks with a primary key, after reading `member` the builder also requires the `key_format` option (the template for the Redis key holding the sorted set). A missing `key_format` aborts the sink build with this SinkError::Config.

Source

Thrown at src/connector/src/sink/formatter/mod.rs:340

                    Some(_) => KEY_FORMAT,
                    None => VALUE_FORMAT,
                };
                let template = b.format_desc.options.get(option_name).ok_or_else(|| {
                    SinkError::Config(anyhow!("Cannot find '{option_name}',please set it."))
                })?;
                Ok(TemplateEncoder::new_string(
                    b.schema,
                    pk_indices,
                    template.clone(),
                ))
            }
            REDIS_VALUE_TYPE_GEO => match pk_indices {
                Some(_) => {
                    let member_name = b.format_desc.options.get(MEMBER_NAME).ok_or_else(|| {
                        SinkError::Config(anyhow!("Cannot find `{MEMBER_NAME}`,please set it."))
                    })?;
                    let template = b.format_desc.options.get(KEY_FORMAT).ok_or_else(|| {
                        SinkError::Config(anyhow!("Cannot find `{KEY_FORMAT}`,please set it."))
                    })?;
                    TemplateEncoder::new_geo_key(
                        b.schema,
                        pk_indices,
                        member_name,
                        template.clone(),
                    )
                }
                None => {
                    let lat_name = b.format_desc.options.get(LAT_NAME).ok_or_else(|| {
                        SinkError::Config(anyhow!("Cannot find `{LAT_NAME}`, please set it."))
                    })?;
                    let lon_name = b.format_desc.options.get(LON_NAME).ok_or_else(|| {
                        SinkError::Config(anyhow!("Cannot find `{LON_NAME}`,please set it."))
                    })?;
                    TemplateEncoder::new_geo_value(b.schema, pk_indices, lat_name, lon_name)
                }
            },

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Add `key_format = '<template>'` to the WITH options.
  2. Confirm `member` is also set, since it is read immediately before this check.
  3. Use correct template placeholders for the key columns (e.g. `%s` for the primary key).

Example fix

// before
WITH (redis_value_type='geospatial', member='%s');
// after
WITH (redis_value_type='geospatial', member='%s', key_format='%s:locations');
Defensive patterns

Strategy: validation

Validate before calling

if value_type == "geospatial" && has_pk && !with_options.contains_key("key_format") {
    return Err("Redis geospatial sink with PK requires `key_format` option".into());
}

Try / catch

match result {
    Err(e) if e.to_string().contains("`key_format`") => {
        eprintln!("Add `key_format = '<template>'` to WITH options: {}", e);
    }
    other => other?,
}

Prevention

When it happens

Trigger: Creating a Redis geospatial sink with a primary key, providing `member` but not `key_format` in the WITH options.

Common situations: Users set `member` for geospatial sinks but forget that, like `string` type with a primary key, the key template `key_format` is mandatory.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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