apache/iceberg · error · RuntimeException

Fail to serialize at field: %s.

Error message

Fail to serialize at field: %s.

What it means

The record-level convert() in RowDataToAvroConverters serializes each field via its converter and getter. If any field conversion throws (type mismatch, null in a non-nullable Avro field, converter failure), it is wrapped in a RuntimeException naming the offending field via 'Fail to serialize at field: <name>.' with the original exception as cause.

Source

Thrown at flink/v2.2/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. Inspect the cause exception to find the real failure, then fix the data or schema at that field.
2. Make the Avro schema field nullable (["null", T]) if nulls are legitimate in the data.
3. Re-derive the Avro schema from the current Flink type so schema and RowData match (AvroSchemaConverter.convertToSchema).
4. Sanitize/coerce values before writing: convert types (e.g. timestamp precision) and replace nulls with defaults for required fields.

Example fix

// before
schema field "ts": {"type":"long","logicalType":"timestamp-millis"}, data has micros TimestampData
// after
regenerate schema with local-timestamp-micros or truncate the value to millis before writing

for (int i = 0; i < row.getArity(); i++) {
  if (schemaField(i).schema.getType() != Schema.Type.UNION && row.getField(i) == null) {
    throw new IllegalArgumentException("null value for non-nullable Avro field: " + schemaField(i).name());
  }
}

try { record = converter.convert(schema, row); } catch (RuntimeException e) { log.error("{} cause={}", e.getMessage(), e.getCause(), e); throw e; }

When it happens

Trigger: Calling convert() on a RowData whose field value does not match the Avro schema at that position: null for a non-nullable field, wrong type for the declared branch, or an unsupported nested value.

Common situations: Writing Flink rows to Iceberg/Avro files where a column holds null but the Avro schema marks it non-null; schema and RowData drifted after a table schema change; decimal/timestamp precision mismatches.

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