apache/flink · error · IllegalArgumentException

Schema provided for '%s' format does not match the table sch

Error message

Schema provided for '%s' format does not match the table schema: %s

What it means

IllegalArgumentException from RegistryAvroFormatFactory.getAvroSchema: when 'avro-confluent-registry.schema' is provided, its converted logical type (after forcing non-nullable) must exactly equal the table's row type. Any difference in field names, order, types, nesting, or nullability triggers this mismatch.

Source

Thrown at flink-formats/flink-avro-confluent-registry/src/main/java/org/apache/flink/formats/avro/registry/confluent/RegistryAvroFormatFactory.java:256

                .getOptional(BEARER_AUTH_TOKEN)
                .ifPresent(v -> properties.put("bearer.auth.token", v));

        if (properties.isEmpty()) {
            return null;
        }
        return properties;
    }

    private static Schema getAvroSchema(String schemaString, RowType rowType) {
        LogicalType convertedDataType =
                AvroSchemaConverter.convertToDataType(schemaString).getLogicalType();

        if (convertedDataType.isNullable()) {
            convertedDataType = convertedDataType.copy(false);
        }

        if (!convertedDataType.equals(rowType)) {
            throw new IllegalArgumentException(
                    format(
                            "Schema provided for '%s' format does not match the table schema: %s",
                            IDENTIFIER, schemaString));
        }

        return new Parser().parse(schemaString);
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Diff the two row types: print AvroSchemaConverter.convertToDataType(schemaString) and the table's derived row type — mismatched field, order, or nullability will show immediately.
2. Adjust the DDL so field names, order, types, and nullability exactly match the Avro schema (top-level nullability is ignored, nested nullability is not).
3. Alternatively drop 'format.schema' and let Flink derive the schema from the table definition.

Example fix

-- before: schema says {'name':'id','type':['null','string']} but DDL had id BIGINT
-- after
CREATE TABLE t (id STRING, ...) WITH ('format'='avro-confluent-registry', 'avro-confluent-registry.schema'='{"type":"record","name":"r","fields":[{"name":"id","type":["null","string"]}]}', ...)

// verify before submitting DDL
DataType fromSchema =
    org.apache.flink.formats.avro.typeutils.AvroSchemaConverter.convertToDataType(schemaString);
LogicalType a = fromSchema.getLogicalType().copy(false); // force not-null like the factory does
LogicalType b = tableRowType;
if (!a.equals(b)) {
    throw new IllegalArgumentException(
        "format.schema does not equal table row type:\n schema=" + a.asSummaryString()
        + "\n table=" + b.asSummaryString());
}

try {
    tableEnv.executeSql(createSql);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("does not match the table schema")) {
        // compare AvroSchemaConverter.convertToDataType(schemaString) against DESCRIBE output
    }
    throw e;
}

When it happens

Trigger: Setting 'format.schema' on an avro-confluent-registry table where the Avro schema's fields differ from the DDL columns; Avro unions producing nullable fields the DDL declares NOT NULL (or vice versa); column order differing between schema and DDL.

Common situations: Copying a producer's Avro schema into the DDL while the CREATE TABLE columns were reordered or retyped; schema drift after the registry schema evolved.

Related errors

• Option %s.%s is required for serialization
• Failed to serialize schema registry.
• Unexpected object type for TIMESTAMP logical type. Received:
• Unexpected object type for DATE logical type. Received: {}
• Unexpected object type for TIME logical type. Received: {}

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