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

Set the header to exactly `milli` or `guess_number_unit` (lowercase).

unrecognized value `{value}` for `{key}`

Error message

unrecognized value `{value}` for `{key}`

What it means

The `x-rw-webhook-json-timestamp-handling` header had a value other than `milli` or `guess_number_unit`. Only those two values (plus absence, meaning default) are recognized; anything else is rejected with HTTP 400 BAD_REQUEST.

Source

Thrown at src/frontend/src/webhook/payload.rs:123

    Ok(JsonProperties {
        use_schema_registry: false,
        timestamp_handling,
        timestamptz_handling,
        time_handling,
        bigint_unsigned_handling,
        handle_toast_columns,
    })
}

fn parse_timestamp_handling(
    headers: &HeaderMap,
    key: &'static str,
) -> Result<Option<TimestampHandling>> {
    match header_value(headers, key)?.as_deref() {
        Some("milli") => Ok(Some(TimestampHandling::Milli)),
        Some("guess_number_unit") => Ok(Some(TimestampHandling::GuessNumberUnit)),
        Some(value) => Err(err(
            anyhow!("unrecognized value `{value}` for `{key}`"),
            StatusCode::BAD_REQUEST,
        )),
        None => Ok(None),
    }
}

fn parse_timestamptz_handling(
    headers: &HeaderMap,
    key: &'static str,
) -> Result<Option<TimestamptzHandling>> {
    header_value(headers, key)?
        .as_deref()
        .map(TimestamptzHandling::from_options)
        .transpose()
        .map_err(|e| {
            err(
                anyhow!(e).context("invalid webhook JSON decoder option"),
                StatusCode::BAD_REQUEST,

View on GitHub (pinned to 6469eb736d)

Solutions

Set the header to exactly `milli` or `guess_number_unit` (lowercase).
Remove the header to use default handling.
Check spelling/whitespace — values are matched literally.
Consult docs for TimestampHandling values supported by your RisingWave version.
If other semantics are needed, transform timestamps client-side to the expected numeric/string form.

Example fix

// before
-H 'x-rw-webhook-json-timestamp-handling: milliseconds'
// after
-H 'x-rw-webhook-json-timestamp-handling: milli'

Defensive patterns

Strategy: validation

Validate before calling

const TS_MODES = ['milli', 'guess_number_unit'];
const v = headers['x-rw-webhook-json-timestamp-handling'];
if (v && !TS_MODES.includes(String(v)))
  throw new Error(`invalid timestamp-handling: ${v} (milli|guess_number_unit)`);

Type guard

const isTimestampHandling = (v) => v === 'milli' || v === 'guess_number_unit';

Try / catch

const v = headers['x-rw-webhook-json-timestamp-handling'];
if (v && !isTimestampHandling(v)) throw new Error(`unrecognized ${v} for x-rw-webhook-json-timestamp-handling`);

Prevention

Keep a shared constant list of valid header values in the producer SDK
Use lowercase exact values — no abbreviations or synonyms
Test webhook headers in staging before production rollout
Omit optional headers unless non-default behavior is required

When it happens

Trigger: POST with header `x-rw-webhook-json-timestamp-handling: seconds`, `auto`, `milliseconds`, or any misspelled value; header set by an SDK using another product's option names.

Common situations: Producers guessing option names (`millisecond` instead of `milli`); copy-pasted headers from other ingestion systems; values with typos or embedded whitespace.

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/d7c04adb84825bc0. Report an issue: GitHub.