apache/iceberg · error · java.lang.RuntimeException

Fail to serialize at field: %s.

Error message

Fail to serialize at field: %s.

What it means

Wrapping error from RowDataToAvroConverters' record converter: an exception escaped while converting one field of a RowData to its Avro representation, and it is rethrown with the offending field name (%s) added for diagnosis. The root cause (class cast, null, or numeric problem) is chained — inspect the cause for the real failure.

Source

Thrown at flink/v2.1/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 wrapped cause ('Caused by') to find the real converter failure and fix the underlying data or schema
2. Validate row data types against the table schema before writing
3. Regenerate the Avro schema from the current table schema so field types align
4. Add null checks / casts in the pipeline for nullable or heterogeneous fields

Example fix

// cause: field "ts" holds String but schema expects long
// before
row.setField(2, "2024-01-01");
// after
row.setField(2, TimestampData.fromLocalDateTime(LocalDateTime.parse("2024-01-01T00:00:00")));

for (int i = 0; i < row.getArity(); i++) {
  Object v = row.getField(i);
  if (v != null && !typeMatches(rowType.getTypeAt(i), v.getClass())) {
    throw new IllegalStateException("Field " + schema.getField(i).name() + " type mismatch: " + v.getClass());
  }
}

try {
  Object avro = recordConverter.convert(schema, row);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Fail to serialize at field:")) {
    LOG.error("Bad field {}. Cause: {}", e.getMessage(), e.getCause());
    // inspect e.getCause() for the underlying converter failure
  } else { throw e; }
}

When it happens

Trigger: Any per-field converter failure during record serialization: type mismatches, null handling errors, converter bugs, or schema/data divergence for a specific field.

Common situations: A single corrupt or wrong-typed field in an otherwise valid row breaks the whole record serialization when writing Avro files; debugging which column caused a serialization batch failure.

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