apache/flink · error · ValidationException

Unsupported value '%s' for option %s. Supported values are %

Error message

Unsupported value '%s' for option %s. Supported values are %s.

What it means

ValidationException from validateEncodingFormatOptions when 'map-null-key.mode' is not one of the JsonFormatOptions.MapNullKeyMode enum names (FAIL, DROP, LITERAL). Checked against the exact enum name set (upper-case), so lowercase values also fail here since the comparison uses .toUpperCase() on the config value before matching the enum-name set.

Source

Thrown at flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonFormatOptionsUtil.java:125

        if (ignoreParseErrors && failOnMissingField) {
            throw new ValidationException(
                    FAIL_ON_MISSING_FIELD.key()
                            + " and "
                            + IGNORE_PARSE_ERRORS.key()
                            + " shouldn't both be true.");
        }
        validateTimestampFormat(tableOptions);
    }

    /** Validator for json encoding format. */
    public static void validateEncodingFormatOptions(ReadableConfig tableOptions) {
        // validator for {@link MAP_NULL_KEY_MODE}
        Set<String> nullKeyModes =
                Arrays.stream(JsonFormatOptions.MapNullKeyMode.values())
                        .map(Objects::toString)
                        .collect(Collectors.toSet());
        if (!nullKeyModes.contains(tableOptions.get(MAP_NULL_KEY_MODE).toUpperCase())) {
            throw new ValidationException(
                    String.format(
                            "Unsupported value '%s' for option %s. Supported values are %s.",
                            tableOptions.get(MAP_NULL_KEY_MODE),
                            MAP_NULL_KEY_MODE.key(),
                            nullKeyModes));
        }
        validateTimestampFormat(tableOptions);
    }

    /** Validates timestamp format which value should be SQL or ISO-8601. */
    static void validateTimestampFormat(ReadableConfig tableOptions) {
        String timestampFormat = tableOptions.get(TIMESTAMP_FORMAT);
        if (!TIMESTAMP_FORMAT_ENUM.contains(timestampFormat)) {
            throw new ValidationException(
                    String.format(
                            "Unsupported value '%s' for %s. Supported values are [SQL, ISO-8601].",
                            timestampFormat, TIMESTAMP_FORMAT.key()));
        }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Use 'FAIL', 'DROP', or 'LITERAL' for 'json.map-null-key.mode'
2. If LITERAL, also set a valid 'json.map-null-key.literal' value
3. Let the DDL path run the validator to catch typos at CREATE time

Example fix

-- before
'json.map-null-key.mode' = 'ignore'

-- after
'json.map-null-key.mode' = 'DROP'

JsonFormatOptionsUtil.validateEncodingFormatOptions(tableOptions);

When it happens

Trigger: CREATE TABLE with 'json.map-null-key.mode' set to an unknown value in an encoding (sink) context; programmatic config without validation.

Common situations: Typos ('faill', 'ignore', 'null'); assuming another connector's option vocabulary; custom factory skipping the encoding validator.

Related errors

• Unsupported map null key handling mode '%s'. Validator shoul
• Unsupported timestamp format '%s'. Validator should have che
• fail-on-missing-field and ignore-parse-errors shouldn't both
• Unsupported value '%s' for %s. Supported values are [SQL, IS
• JSON format doesn't support failOnMissingField and ignorePar

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/fc05b37a96a4cbba. Report an issue: GitHub.