apache/iceberg · error · UnsupportedOperationException

Cannot convert unsupported type to Spark: ${primitive}

Error message

Cannot convert unsupported type to Spark: ${primitive}

What it means

The primitive() method in TypeToSparkType throws UnsupportedOperationException when it encounters an Iceberg primitive type it has no mapping for, listing the offending type in the message. It is a catch-all for type system drift between Iceberg and Spark.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/TypeToSparkType.java:154

        } else {
          return TimestampNTZType$.MODULE$;
        }
      case STRING:
        return StringType$.MODULE$;
      case UUID:
        // use String
        return StringType$.MODULE$;
      case FIXED:
        return BinaryType$.MODULE$;
      case BINARY:
        return BinaryType$.MODULE$;
      case DECIMAL:
        Types.DecimalType decimal = (Types.DecimalType) primitive;
        return DecimalType$.MODULE$.apply(decimal.precision(), decimal.scale());
      case UNKNOWN:
        return NullType$.MODULE$;
      default:
        throw new UnsupportedOperationException(
            "Cannot convert unsupported type to Spark: " + primitive);
    }
  }

  private Metadata fieldMetadata(int fieldId) {
    if (MetadataColumns.metadataFieldIds().contains(fieldId)) {
      return new MetadataBuilder().putBoolean(METADATA_COL_ATTR_KEY, true).build();
    }

    return Metadata.empty();
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Upgrade the iceberg-spark runtime to a version that supports the type
Inspect the schema (table.schema()) and remove/migrate unsupported column types
If the type is newly added to Iceberg, add a case in TypeToSparkType.primitive

Example fix

// before
default: throw new UnsupportedOperationException("Cannot convert unsupported type to Spark: " + primitive);
// after
case UUID: return StringType$.MODULE$;
default: throw new UnsupportedOperationException("Cannot convert unsupported type to Spark: " + primitive);

Defensive patterns

Strategy: try-catch

Validate before calling

for (Types.NestedField f : table.schema().columns()) { SparkSchemaUtil.convert(f.type()); } // throws early if unsupported

Try / catch

try { Schema spark = SparkSchemaUtil.convert(icebergSchema); } catch (UnsupportedOperationException e) { /* inspect e.getMessage() for the offending primitive and remap it */ }

Prevention

Upgrade the Spark runtime before adopting tables written with newer Iceberg types
Validate schema convertibility with SparkSchemaUtil.convert during migrations

When it happens

Trigger: Converting an Iceberg schema to a Spark schema where a primitive is not covered by the switch (anything besides boolean/int/long/float/double/date/time/timestamp/string/binary/decimal/uuid/unknown in unhandled versions).

Common situations: Tables written with a newer Iceberg spec type being read by an older iceberg-spark runtime; custom primitive extensions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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