apache/flink · error · ValidationException

Debezium JSON serialization doesn't support '%s.%s' option b

Error message

Debezium JSON serialization doesn't support '%s.%s' option been set to true.

What it means

Thrown by the Debezium JSON encoding-format factory during table-environment validation. Debezium JSON serialization only writes the 'before', 'after', and 'op' envelope fields, so emitting an embedded 'schema' (JSON schema include) is not implemented. Setting 'debezium-json.schema-include' = true on a table used as a SINK therefore fails fast at DDL/CREATE time with a ValidationException.

Source

Thrown at flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/debezium/DebeziumJsonFormatFactory.java:159

        options.add(JSON_MAP_NULL_KEY_MODE);
        options.add(JSON_MAP_NULL_KEY_LITERAL);
        options.add(ENCODE_DECIMAL_AS_PLAIN_NUMBER);
        options.add(ENCODE_IGNORE_NULL_FIELDS);
        return options;
    }

    /** Validator for debezium decoding format. */
    private static void validateDecodingFormatOptions(ReadableConfig tableOptions) {
        JsonFormatOptionsUtil.validateDecodingFormatOptions(tableOptions);
    }

    /** Validator for debezium encoding format. */
    private static void validateEncodingFormatOptions(ReadableConfig tableOptions) {
        JsonFormatOptionsUtil.validateEncodingFormatOptions(tableOptions);

        // validator for {@link SCHEMA_INCLUDE}
        if (tableOptions.get(SCHEMA_INCLUDE)) {
            throw new ValidationException(
                    String.format(
                            "Debezium JSON serialization doesn't support '%s.%s' option been set to true.",
                            IDENTIFIER, SCHEMA_INCLUDE.key()));
        }
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Remove 'debezium-json.schema-include' = true (or set it to false) from the sink table's WITH options.
2. If you meant to consume (read) Debezium messages that carry a schema, use the table as a SOURCE instead — schema-include is only supported for decoding.
3. If you need to emit schemas with CDC envelopes, use a different CDC format (e.g. Canal JSON with its own options, or Debezium Avro via confluent-registry) that supports schema emission.

Example fix

-- before
CREATE TABLE kafka_sink (...) WITH (
  'connector' = 'kafka',
  'topic' = 'cdc-out',
  'format' = 'debezium-json',
  'debezium-json.schema-include' = 'true'
);
-- after
CREATE TABLE kafka_sink (...) WITH (
  'connector' = 'kafka',
  'topic' = 'cdc-out',
  'format' = 'debezium-json'
);

// Before creating the sink table, check the format options
boolean schemaInclude = tableOptions.getOptional(JsonFormatOptionsUtil.JSON_SCHEMA_INCLUDE)
        .orElse(false);
boolean isSink = /* table is written to */;
if (isSink && "debezium-json".equals(format) && schemaInclude) {
    throw new IllegalArgumentException(
        "Remove 'debezium-json.schema-include' for debezium-json sinks");
}

No catch needed: it fails at DDL validation time. Wrap Catalog/TableEnvironment executeSql in try-catch ValidationException to surface a friendly message if you build DDL dynamically.

When it happens

Trigger: Creating a table with 'format' = 'debezium-json' and a connector that sinks (writes) to it, plus FORMAT option 'debezium-json.schema-include' = true. The factory method validateEncodingFormatOptions checks tableOptions.get(SCHEMA_INCLUDE) and throws before any job runs.

Common situations: Copy-pasting a Debezium source (kafka connector reading Debezium topics with schema-include true) table DDL and reusing it as a sink target; assuming the decoding option is symmetric for encoding; migrating from JSON format where json schema-include is tolerated.

Related errors

• Please invoke DeserializationSchema#deserialize(byte[], Coll
• The "before" field of %s message is null, if you are using D
• JSON format doesn't support failOnMissingField and ignorePar
• Unsupported timestamp format '%s'. Validator should have che
• Unsupported map null key handling mode '%s'. Validator shoul

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