apache/iceberg · error · RuntimeException

Fail to serialize at field: %s.

Error message

Fail to serialize at field: %s.

What it means

createRowConverter builds a converter that serializes each RowData field into a GenericRecord. Any Throwable thrown while converting an individual field (type mismatch with the Avro schema, NPE from mismatched field order, unsupported nested type, etc.) is rethrown as a RuntimeException annotated with the field name via String.format("Fail to serialize at field: %s.").

Source

Thrown at flink/v1.20/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 (`t`) chained in the RuntimeException — it names the real conversion failure; fix that root cause.
2. Verify the Flink RowType and the target Avro schema have identical field names, order, and types.
3. Recreate the converter after any schema evolution — stale converters built for the old schema fail on new rows.
4. Locate and fix or filter the offending data row(s); the field name in the message narrows the column to check.
5. If caused by nested converters, apply the fix at the nested level (e.g. correct timestamp precision or union shape).

Example fix

// before
Record record = ...; // built with old schema (3 fields)
rowConverter.convert(recordSchema /* 4 fields */, row); // fails at 4th field
// after
RowType rowType = (RowType) tableSchema.toPhysicalRowDataType().getLogicalType();
RowDataToAvroConverter converter = RowDataToAvroConverters.createConverter(rowType, false);
converter.convert(updatedRecordSchema, row); // schemas aligned

if (row.getArity() != schema.getFields().size()) {
  throw new IllegalStateException("Row arity " + row.getArity() + " != schema fields " + schema.getFields().size());
}

try {
  GenericRecord rec = rowConverter.convert(recordSchema, row);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Fail to serialize at field:")) {
    LOG.error("Field serialization failed: {} cause: {}", e.getMessage(), e.getCause(), e);
    // route row to DLQ or fix schema alignment
  } else throw e;
}

When it happens

Trigger: RowDataToAvroConverters row conversion where fieldConverters[i].convert(...) throws — e.g. field value's LogicalType doesn't match the Avro field schema, DecimalData/stringData conversion failure, or the inner converter throws (including error 1260's union rejection) for the field named in the message.

Common situations: Row schema and Avro schema drifted out of sync after a schema change; field ordering mismatch causing a value to be converted against the wrong Avro field; a single bad row (wrong precision timestamp, malformed decimal) failing a whole Flink job writing Avro files.

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/0cc05f70e286ffb1. Report an issue: GitHub.