apache/iceberg · error · RuntimeException

Fail to serialize at field: %s.

Error message

Fail to serialize at field: %s.

What it means

This error wraps any Throwable thrown while converting a single Flink RowData field to its Avro representation during record serialization. The wrapper preserves the original cause as the 'cause' and identifies the failing field by its name, since the underlying conversion failure could be a null mismatch, an unsupported value, or an internal converter error. It exists so a serialization failure in a large row can be attributed to a specific field.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/formats/avro/RowDataToAvroConverters.java:333

    final int length = rowType.getFieldCount();

    return new RowDataToAvroConverter() {
      private static final long serialVersionUID = 1L;

      @Override
      public Object convert(Schema schema, Object object) {
        final RowData row = (RowData) object;
        final List<Schema.Field> fields = schema.getFields();
        final GenericRecord record = new GenericData.Record(schema);
        for (int i = 0; i < length; ++i) {
          final Schema.Field schemaField = fields.get(i);
          try {
            Object avroObject =
                fieldConverters[i].convert(
                    schemaField.schema(), fieldGetters[i].getFieldOrNull(row));
            record.put(i, avroObject);
          } catch (Throwable t) {
            throw new RuntimeException(
                String.format("Fail to serialize at field: %s.", schemaField.name()), t);
          }
        }
        return record;
      }
    };
  }

  private static RowDataToAvroConverter createArrayConverter(
      ArrayType arrayType, boolean legacyTimestampMapping) {
    LogicalType elementType = arrayType.getElementType();
    final ArrayData.ElementGetter elementGetter = ArrayData.createElementGetter(elementType);
    final RowDataToAvroConverter elementConverter =
        createConverter(arrayType.getElementType(), legacyTimestampMapping);

    return new RowDataToAvroConverter() {
      private static final long serialVersionUID = 1L;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Read the 'cause' of the RuntimeException to find the real conversion failure.
2. Check the named field's data type and the actual runtime values against the Avro schema.
3. Ensure the RowData was produced with the same schema used to build the converters (schema evolution drift is a common cause).
4. For nullable Avro fields, verify the field getter returns null correctly rather than an incompatible default.

Example fix

// before
// failing: field 'ts' is TIMESTAMP(6) but schema expects timestampMillis
// after
// cast/adjust the column before writing, e.g. in Flink SQL:
// SELECT CAST(ts AS TIMESTAMP(3)) AS ts, ... FROM source

row.getField(i) != null || avroSchema.getFields().get(i).schema().getType() == Schema.Type.NULL; // validate nullability per field before writing

try { writer.write(record); } catch (RuntimeException e) { Throwable cause = e.getCause(); LOG.error("Avro serialization failed at field: {}", e.getMessage(), cause); throw e; }

When it happens

Trigger: RowDataToAvroConverters.convert() creates a value getter/converter pair per field; calling the returned AvroValueConverter or writing records via an Avro writer when any field converter throws (e.g. unexpected row type, null in a non-nullable field, wrong internal data structure).

Common situations: Writing Flink RowData to Avro files or Kafka topics where one column's runtime value does not match the declared schema (e.g. a timestamp with wrong precision, a map with unexpected key type, or a Decimal with wrong scale after a schema change).

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• The Avro schema is not a nullable type: ${schema}
• Fail to serialize at field: %s.
• Fail to serialize at field: %s.
• Fail to serialize at field: %s.
• Unsupported type:

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/c4bef7ff14c9a9dc. Report an issue: GitHub.