apache/iceberg · error · java.lang.IllegalArgumentException

Unsupported type: ${primitive}

Error message

Unsupported type: ${primitive}

What it means

The Iceberg Spark planned Avro reader throws IllegalArgumentException when an Avro field's primitive type is outside its supported set (NULL, BOOLEAN, INT, LONG, FLOAT, DOUBLE, STRING, FIXED, BYTES, ENUM are handled). Any other Avro type reaching this primitive-level branch — typically a RECORD/ARRAY/MAP/UNION arriving where a primitive was expected — indicates a malformed or unexpected schema.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/data/SparkPlannedAvroReader.java:188

        case LONG:
          return ValueReaders.longs();
        case FLOAT:
          if (partner != null && partner.typeId() == Type.TypeID.DOUBLE) {
            return ValueReaders.floatsAsDoubles();
          }
          return ValueReaders.floats();
        case DOUBLE:
          return ValueReaders.doubles();
        case STRING:
          return SparkValueReaders.strings();
        case FIXED:
          return ValueReaders.fixed(primitive.getFixedSize());
        case BYTES:
          return ValueReaders.bytes();
        case ENUM:
          return SparkValueReaders.enums(primitive.getEnumSymbols());
        default:
          throw new IllegalArgumentException("Unsupported type: " + primitive);
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the Avro schema of the data files matches the Iceberg table schema (refresh metadata if the table evolved)
2. Rewrite the data files so nested types are properly declared rather than appearing in primitive positions
3. Upgrade Iceberg to a version with broader Avro type support
4. Use avro-tools getschema to diff the file schema against expectations and fix the producing writer

Example fix

// before: Avro field declared as union {"type":["null","string"]} where reader expects a primitive
// after: align schema with table, or handle unions at the record level
{"name":"note","type":"string","default":""}

import org.apache.avro.Schema;
boolean primitiveSafe(Schema s) {
  switch (s.getType()) {
    case NULL: case BOOLEAN: case INT: case LONG: case FLOAT: case DOUBLE:
    case STRING: case FIXED: case BYTES: case ENUM: return true;
    default: return false; // RECORD/ARRAY/MAP/UNION must not hit the primitive branch
  }
}

When it happens

Trigger: Reading Avro data where a field's schema type does not match the reader's dispatch — e.g. a nested RECORD/UNION hitting the primitive switch due to schema mismatch between expected Iceberg schema and the file's Avro schema.

Common situations: Schema drift between the Iceberg table schema and the underlying Avro files; hand-written or third-party Avro files with unusual types; Avro spec features not modeled by this reader.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unknown logical type: ${logicalType}
• Unknown logical type:
• Unsupported type:
• Unsupported type: ${primitive}
• Unknown logical type: ${logicalType}

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