What causes "unrecognized {} value {}" in risingwavelabs/risingwave?

Set the option value to exactly "jsonb" or "map" (lowercase, no whitespace).

unrecognized {} value {}

Error message

unrecognized {} value {}

What it means

MapHandling::from_options rejects an unknown value for its config option (only "jsonb" and "map" are supported). It is thrown via anyhow::bail! whenever the option key is present but its value matches neither accepted mode. This prevents silently misinterpreting how Avro map-typed fields should be decoded.

Source

Thrown at src/connector/codec/src/decoder/avro/schema.rs:66

/// How to convert the map type from the input encoding to RisingWave's datatype.
///
/// XXX: Should this be `avro.map.handling.mode`? Can it be shared between Avro and Protobuf?
#[derive(Debug, Copy, Clone)]
pub enum MapHandling {
    Jsonb,
    Map,
}

impl MapHandling {
    pub const OPTION_KEY: &'static str = "map.handling.mode";

    pub fn from_options(
        options: &std::collections::BTreeMap<String, String>,
    ) -> anyhow::Result<Option<Self>> {
        let mode = match options.get(Self::OPTION_KEY).map(std::ops::Deref::deref) {
            Some("jsonb") => Self::Jsonb,
            Some("map") => Self::Map,
            Some(v) => bail!("unrecognized {} value {}", Self::OPTION_KEY, v),
            None => return Ok(None),
        };
        Ok(Some(mode))
    }
}

/// This function expects original schema (with `Ref`).
/// TODO: change `map_handling` to some `Config`, and also unify debezium.
pub fn avro_schema_to_fields(
    schema: &Schema,
    map_handling: Option<MapHandling>,
) -> anyhow::Result<Vec<Field>> {
    let resolved = ResolvedSchema::try_from(schema)?;
    let mut ancestor_records: Vec<String> = vec![];
    let root_type = avro_type_mapping(
        schema,
        &mut ancestor_records,
        resolved.get_names(),

View on GitHub (pinned to 6469eb736d)

Solutions

Set the option value to exactly "jsonb" or "map" (lowercase, no whitespace).
Remove the option key entirely if the default (no map handling) is desired.
Check the connector config for typos or trailing characters and validate casing.

Example fix

// before
properties['codec.decoding.avro.map-handling'] = 'Jsonb';
// after
properties['codec.decoding.avro.map-handling'] = 'jsonb';

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED = ["jsonb", "map"];
const v = options.get("codec.decoding.avro.map-handling");
if (v !== undefined && !ALLOWED.includes(v)) {
  throw new Error(`unrecognized map-handling value ${v}; expected one of ${ALLOWED.join(", ")}`);
}

Prevention

Keep connector option values in a shared constant/enum rather than inline strings.
Validate source options at config submission time, not at decode time.
Watch for case and whitespace when copying values from documentation.

When it happens

Trigger: Calling MapHandling::from_options with a BTreeMap that contains the MapHandling OPTION_KEY set to any value other than "jsonb" or "map" (e.g. "json", "object", or a typo like "jsonb " with trailing whitespace).

Common situations: Debezium/Avro connector config with a misspelled or outdated value for the map handling option; copy-pasting config from docs for a different engine; whitespace/case mistakes like "JSONB".

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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