apache/flink · error · org.apache.flink.formats.json.JsonParseException

Unable to deserialize VARIANT value.

Error message

Unable to deserialize VARIANT value.

What it means

Thrown by JsonToRowDataConverters.convertToVariant when a JSON node declared as VARIANT in the table schema cannot be re-parsed into a BinaryVariant via BinaryVariantInternalBuilder.parseJson. The deserializer runs the node's textual form through the VARIANT parser, and any IOException from that parser is wrapped into this JsonParseException. It means the incoming JSON value is not representable as a VARIANT even though it arrived as valid JSON.

Source

Thrown at flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonToRowDataConverters.java:281

        LocalDate localDate = parsedTimestampWithLocalZone.query(TemporalQueries.localDate());

        return TimestampData.fromInstant(
                LocalDateTime.of(localDate, localTime).toInstant(ZoneOffset.UTC));
    }

    private StringData convertToString(JsonNode jsonNode) {
        if (jsonNode.isContainerNode()) {
            return StringData.fromString(jsonNode.toString());
        } else {
            return StringData.fromString(jsonNode.asText());
        }
    }

    private BinaryVariant convertToVariant(JsonNode jsonNode) {
        try {
            return BinaryVariantInternalBuilder.parseJson(jsonNode.toString(), false);
        } catch (IOException e) {
            throw new JsonParseException("Unable to deserialize VARIANT value.", e);
        }
    }

    private byte[] convertToBytes(JsonNode jsonNode) {
        try {
            return jsonNode.binaryValue();
        } catch (IOException e) {
            throw new JsonParseException("Unable to deserialize byte array.", e);
        }
    }

    private JsonToRowDataConverter createDecimalConverter(DecimalType decimalType) {
        final int precision = decimalType.getPrecision();
        final int scale = decimalType.getScale();
        return jsonNode -> {
            BigDecimal bigDecimal;
            if (jsonNode.isBigDecimal()) {
                bigDecimal = jsonNode.decimalValue();

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Inspect the failing JSON record (log the raw message) and identify the field declared VARIANT that fails to parse
2. If the column is not truly a VARIANT, change its type in the DDL to the concrete JSON-compatible type (STRING, ROW, ARRAY, MAP)
3. If the data is correct but occasional records are bad, set 'json.ignore-parse-errors' = true to skip them (only for Canal/Debezium/JSON formats that support it)
4. Upgrade flink-formats-json / flink-table to a version whose VARIANT parser accepts the value, if this is a parser bug

Example fix

// before
CREATE TABLE t (v VARIANT) WITH ('connector'='kafka', 'format'='json', ...);

// after: use STRING if the payload is arbitrary JSON text
CREATE TABLE t (v STRING) WITH ('connector'='kafka', 'format'='json', ...);

// Before assigning VARIANT, check the value parses as JSON the variant parser accepts
ObjectNode node = mapper.readValue(json, ObjectNode.class);
try { BinaryVariantInternalBuilder.parseJson(node.toString(), false); }
catch (IOException e) { /* route record to quarantine, do not send to VARIANT column */ }

catch (JsonParseException e) when 'Unable to deserialize VARIANT' — inspect cause IOException; quarantine the record and keep the source running rather than retrying the same bytes.

When it happens

Trigger: A table column declared as VARIANT where the JSON value at that position fails BinaryVariantInternalBuilder.parseJson (e.g. a value form the variant parser rejects, such as an unsupported literal or a node whose string form the parser cannot consume). Reached through JsonRowDataDeserializationSchema / the 'json' format on a Kafka source whose derived schema contains VARIANT.

Common situations: CDC or upstream producers emitting values that do not round-trip through the VARIANT parser; schema evolution marking a column VARIANT when the payload is not variant-compatible; version mismatches between the VARIANT parser and the JSON payload.

Related errors

• JSON format doesn't support failOnMissingField and ignorePar
• Please invoke DeserializationSchema#deserialize(byte[], Coll
• Failed to deserialize JSON '%s'.
• Unable to deserialize byte array.
• JSON format doesn't support non-string as key type of map. T

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