apache/iceberg · error · java.lang.UnsupportedOperationException

Cannot convert type to SQL

Error message

Cannot convert type to SQL: <primitive>

What it means

Spark3Util.primitive converts an Iceberg primitive Type into a SQL type string for DESCRIBE output. The switch covers the known primitive kinds; any primitive type not represented (e.g. newly added spec types) falls through to UnsupportedOperationException since no SQL spelling exists for it.

Solutions

1. Upgrade the Iceberg Spark runtime to a version that knows the type
2. Rewrite the schema to use fully supported primitive types
3. Inspect the table with a core tool (IcebergInspect/ShowCreateTable alternatives) that handles the type

Example fix

// before
// old runtime reading a table with a new primitive type
// after
// upgrade: implementation 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<newer-version>'

for (Types.NestedField f : schema.columns()) {
  if (f.type() instanceof Types.PrimitiveType) {
    // ensure type is one of the known SQL-mappable primitives
  }
}

try {
  spark.sql("DESCRIBE TABLE " + tableName);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Cannot convert type to SQL")) {
    // upgrade Iceberg runtime or inspect the table with core APIs
  }
}

When it happens

Trigger: DESCRIBE TABLE (or describeSpannedTable) on a table whose schema contains a primitive type not handled by the switch — typically a newer Iceberg type such as an unknown/nanoTime-like variant or future spec additions.

Common situations: Tables written by a newer Iceberg/spec version then inspected by an older Spark integration; custom type extensions.

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

• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple ordering clauses
• ALTER TABLE contains multiple ordering clauses
• ALTER TABLE has no changes: missing both distribution and…

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

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:644

        case DOUBLE:
          return "double";
        case DATE:
          return "date";
        case TIME:
          return "time";
        case TIMESTAMP:
          return "timestamp";
        case STRING:
        case UUID:
          return "string";
        case FIXED:
        case BINARY:
          return "binary";
        case DECIMAL:
          Types.DecimalType decimal = (Types.DecimalType) primitive;
          return "decimal(" + decimal.precision() + "," + decimal.scale() + ")";
      }
      throw new UnsupportedOperationException("Cannot convert type to SQL: " + primitive);
    }
  }

  private static class DescribeExpressionVisitor
      extends ExpressionVisitors.ExpressionVisitor<String> {
    private static final DescribeExpressionVisitor INSTANCE = new DescribeExpressionVisitor();

    private DescribeExpressionVisitor() {}

    @Override
    public String alwaysTrue() {
      return "true";
    }

    @Override
    public String alwaysFalse() {
      return "false";
    }

View on GitHub (pinned to 86d9c8fc54)