risingwavelabs/risingwave · error · SinkError::Config

Cannot find '{KEY_FORMAT}', please set it or use JSON

Error message

Cannot find '{KEY_FORMAT}', please set it or use JSON

What it means

When creating a Redis sink with template encoding and value type `string` (the default), RisingWave requires a `key_format` option that defines the template used to build the Redis key. The sink's `validate` step throws this SinkError::Config when the `key_format` option is absent from the FORMAT ... ENCODE ... options clause, telling the user to either set it or switch to a JSON-based encoding.

Source

Thrown at src/connector/src/sink/redis.rs:353

            .iter()
            .enumerate()
            .filter(|(k, _)| self.pk_indices.contains(k))
            .map(|(_, v)| (v.name.clone(), v.data_type.clone()))
            .collect();
        if matches!(
            self.format_desc.encode,
            super::catalog::SinkEncode::Template
        ) {
            match self
                .format_desc
                .options
                .get(REDIS_VALUE_TYPE)
                .map(|s| s.as_str())
            {
                // if not set, default to string
                Some(REDIS_VALUE_TYPE_STRING) | None => {
                    let key_format = self.format_desc.options.get(KEY_FORMAT).ok_or_else(|| {
                        SinkError::Config(anyhow!(
                            "Cannot find '{KEY_FORMAT}', please set it or use JSON"
                        ))
                    })?;
                    TemplateStringEncoder::check_string_format(key_format, &pk_map)?;
                    let value_format =
                        self.format_desc.options.get(VALUE_FORMAT).ok_or_else(|| {
                            SinkError::Config(anyhow!(
                                "Cannot find `{VALUE_FORMAT}`, please set it or use JSON"
                            ))
                        })?;
                    TemplateStringEncoder::check_string_format(value_format, &all_map)?;
                }
                Some(REDIS_VALUE_TYPE_GEO) => {
                    let key_format = self.format_desc.options.get(KEY_FORMAT).ok_or_else(|| {
                        SinkError::Config(anyhow!(
                            "Cannot find '{KEY_FORMAT}', please set it or use JSON"
                        ))
                    })?;

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Add `key_format = '<template>'` to the ENCODE TEMPLATE options, e.g. key_format = 'prefix::{pk}' alongside value_format
  2. Alternatively switch the sink to a JSON encoding which does not require key_format
  3. Ensure the option key is spelled exactly `key_format` (lowercase with underscore)

Example fix

-- before
CREATE SINK s FROM mv WITH (connector='redis', redis.url='redis://127.0.0.1:6379', format template, encode template (value_format = 'f={v}'));
-- after
CREATE SINK s FROM mv WITH (connector='redis', redis.url='redis://127.0.0.1:6379', format template, encode template (key_format = 'kv::{pk}', value_format = 'f={v}'));
Defensive patterns

Strategy: validation

Validate before calling

-- ensure options contains key_format before CREATE SINK (template encoding, string value type)
-- options.contains_key("key_format")

Try / catch

match result.err() { Some(e) if e.contains("key_format") => add_missing_option("key_format"), _ => propagate(result) }

Prevention

When it happens

Trigger: Creating a Redis sink with ENCODE TEMPLATE whose `redis_value_type` is `string` or unset, while the options map contains no `key_format` entry; validation runs at CREATE SINK time via RedisSink::validate (src/connector/src/sink/redis.rs:352).

Common situations: Forgetting the `key_format='...'` option in CREATE SINK ... WITH (connector = 'redis'); copying examples that use JSON encoding into a template-encoding sink; renaming the option (e.g. `key.template`) by mistake.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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