apache/iceberg · error · IllegalArgumentException

Encountered an unsupported ORC type during a write from…

Error message

Encountered an unsupported ORC type during a write from Spark.

What it means

SparkOrcWriter.createFieldGetter() maps an ORC TypeDescription category to a getter that extracts the field from Spark's InternalRow. If the ORC type is a category the writer does not support (the default branch of the switch over TypeDescription.Category), it throws IllegalArgumentException indicating an unsupported ORC type during a write from Spark. This occurs during writer construction for a column.

Solutions

Print the column's TypeDescription and confirm its category is supported (struct, list, map, and the primitive cases handled by the switch)
Ensure the ORC schema is derived from the Iceberg table schema, not hand-built
Upgrade Iceberg if the ORC type comes from a newer spec/version with additional categories
Fix any custom schema-evolution or file-merging logic that introduces unsupported ORC categories

Defensive patterns

Strategy: validation

Validate before calling

switch (orcType.getCategory()) {
  case STRUCT: case LIST: case MAP: case BOOLEAN: case BYTE: case SHORT: case INT:
  case LONG: case FLOAT: case DOUBLE: case STRING: case VARCHAR: case CHAR:
  case DECIMAL: case TIMESTAMP: case TIMESTAMP_INSTANT: case DATE: case BINARY:
    break;
  default:
    throw new IllegalStateException("Unsupported ORC category: " + orcType.getCategory());
}

Try / catch

try {
  spark.sql("INSERT INTO catalog.db.tbl SELECT * FROM src");
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("unsupported ORC type during a write from Spark")) {
    // inspect the ORC schema of the offending column and fix it before retrying
  } else {
    throw e;
  }
}

Prevention

Never inject externally built ORC schemas into Iceberg write paths
Validate ORC file schemas with orc-tools when ingesting files from other producers
Keep the ORC schema strictly derived from the Iceberg table schema

When it happens

Trigger: Building a field getter for an ORC column whose TypeDescription.Category is not one of the handled cases (e.g. unusual ORC categories not produced by the normal Iceberg-to-ORC mapping).

Common situations: Writing to ORC files with externally supplied or corrupted schemas; bugs in schema-mapping code that produce ORC types outside the supported set; writing Iceberg data with a hand-crafted ORC writer configuration.

Related errors

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/data/SparkOrcWriter.java:221

            (row, ordinal) ->
                row.getDecimal(ordinal, fieldType.getPrecision(), fieldType.getScale());
        break;
      case STRING:
      case CHAR:
      case VARCHAR:
        fieldGetter = SpecializedGetters::getUTF8String;
        break;
      case STRUCT:
        fieldGetter = (row, ordinal) -> row.getStruct(ordinal, fieldType.getChildren().size());
        break;
      case LIST:
        fieldGetter = SpecializedGetters::getArray;
        break;
      case MAP:
        fieldGetter = SpecializedGetters::getMap;
        break;
      default:
        throw new IllegalArgumentException(
            "Encountered an unsupported ORC type during a write from Spark.");
    }

    return (row, ordinal) -> {
      if (row.isNullAt(ordinal)) {
        return null;
      }
      return fieldGetter.getFieldOrNull(row, ordinal);
    };
  }

  interface FieldGetter<T> extends Serializable {

    /**
     * Returns a value from a complex Spark data holder such ArrayData, InternalRow, etc... Calls
     * the appropriate getter for the expected data type.
     *
     * @param row Spark's data representation

View on GitHub (pinned to 86d9c8fc54)