apache/iceberg · error · IllegalArgumentException

Unhandled type ${primitive}

Error message

Unhandled type ${primitive}

What it means

SparkOrcReader.primitive maps ORC primitive types to Spark ORC value readers; the default branch throws IllegalArgumentException for ORC primitives it cannot handle. The BINARY branch additionally special-cases UUID; anything after that falls through to the throw.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/data/SparkOrcReader.java:131

          return OrcValueReaders.floats();
        case DOUBLE:
          return OrcValueReaders.doubles();
        case TIMESTAMP_INSTANT:
        case TIMESTAMP:
          return SparkOrcValueReaders.timestampTzs();
        case DECIMAL:
          return SparkOrcValueReaders.decimals(primitive.getPrecision(), primitive.getScale());
        case CHAR:
        case VARCHAR:
        case STRING:
          return SparkOrcValueReaders.utf8String();
        case BINARY:
          if (Type.TypeID.UUID == iPrimitive.typeId()) {
            return SparkOrcValueReaders.uuids();
          }
          return OrcValueReaders.bytes();
        default:
          throw new IllegalArgumentException("Unhandled type " + primitive);
      }
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg Spark runtime to a version whose SparkOrcReader covers the type.
2. Rewrite the ORC files with supported types (cast columns before writing).
3. Exclude the unsupported column from the scan projection if possible.

// check ORC schema types against supported readers before scanning
TypeDescription.getSchema(file).getChildren().forEach(c -> /* verify c.getCategory() is handled */);

boolean readable(TypeDescription t) { switch (t.getCategory()) { /* list handled categories */ default: return false; } }

try { scan/table read } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unhandled type")) { /* exclude column or upgrade runtime */ } else throw e; }

When it happens

Trigger: Reading ORC data files into Spark via Iceberg when the file schema contains an ORC primitive type with no reader mapping (types not in the handled set of the reader builder).

Common situations: ORC files written by external engines or newer writers with types this Iceberg version doesn't map (e.g. new ORC type ids).

Related errors

• Unhandled type
• Unhandled type
• Unhandled type {primitive}
• Unhandled type
• Unhandled type

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