apache/iceberg · error · UnsupportedOperationException

Default values are not supported

Error message

Default values are not supported

What it means

UpdateSchema.addColumn(parent, name, type, doc, defaultValue) is a default API method that throws UnsupportedOperationException because the concrete implementation does not support initial default values on new columns. Default-value support is optional; only implementations capable of writing defaults override this overload.

Source

Thrown at api/src/main/java/org/apache/iceberg/UpdateSchema.java:239

   * is added to the list element struct, and if it identifies a map, the new column is added to the
   * map's value struct.
   *
   * <p>The given name is used to name the new column and names containing "." are not handled
   * differently.
   *
   * <p>If type is a nested type, its field IDs are reassigned when added to the existing schema.
   *
   * @param parent name of the parent struct to the column will be added to
   * @param name name for the new column
   * @param type type for the new column
   * @param doc documentation string for the new column
   * @param defaultValue a default value for the column in existing rows
   * @return this for method chaining
   * @throws IllegalArgumentException If parent doesn't identify a struct
   */
  default UpdateSchema addColumn(
      String parent, String name, Type type, String doc, Literal<?> defaultValue) {
    throw new UnsupportedOperationException("Default values are not supported");
  }

  /**
   * Add a new required top-level column.
   *
   * <p>Adding a required column without a default is an incompatible change that can break reading
   * older data. To make this a compatible change, add a default value by calling {@link
   * #updateColumnDefault(String, Literal)} or use {@link #addRequiredColumn(String, Type, String,
   * Literal)} instead. To suppress exceptions thrown when an incompatible change is detected, call
   * {@link #allowIncompatibleChanges()}.
   *
   * <p>Because "." may be interpreted as a column path separator or may be used in field names, it
   * is not allowed in names passed to this method. To add to nested structures or to add fields
   * with names that contain ".", use {@link #addRequiredColumn(String, String, Type)}.
   *
   * <p>If type is a nested type, its field IDs are reassigned when added to the existing schema.
   *
   * @param name name for the new column

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use the overload without a default value: addColumn(parent, name, type, doc).
2. Add the column as optional with no default and backfill values in a separate rewrite step.
3. Verify the UpdateSchema implementation (class name in the message) supports defaults before using the overload.
4. Upgrade to an Iceberg version/implementation with schema default-value support (requires format version 3 features).

Example fix

// before
updateSchema.addColumn(null, "count", Types.IntegerType.get(), "doc", Literals.from(0));

// after
updateSchema.addOptionalColumn("count", Types.IntegerType.get(), "doc");

// pass null default to avoid the unsupported overload:
// updateSchema.addColumn(parent, name, type, doc) instead of the 5-arg overload

boolean supportsDefaults = updateSchema instanceof SupportsDefaults; // check implementation capability

try {
  updateSchema.addColumn(parent, name, type, doc, defaultValue);
} catch (UnsupportedOperationException e) {
  updateSchema.addOptionalColumn(name, type, doc); // add without default
}

When it happens

Trigger: Calling the five-argument addColumn overload with a non-null (or any) Literal default value on an UpdateSchema implementation that has not overridden it, e.g. table.updateSchema().addColumn(null, "col", Types.IntegerType.get(), "doc", Literals.from(5)).

Common situations: Adding a column with an initial default value through a transaction or catalog path lacking default-write support; porting code written against newer Iceberg versions to an implementation that predates default values.

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

• %s doesn't implement copyWithStats
• %s doesn't implement validateFilesExist
• %s doesn't implement cleanupLevel
• %s doesn't implement cleanExpiredMetadata
• Managing snapshots is not supported by + getClass().getName(

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