apache/iceberg · error · UnsupportedOperationException

Equality field ids not supported for this writer type

Error message

Equality field ids not supported for this writer type

What it means

FileWriterBuilderImpl.equalityFieldIds(...) configures equality-delete field IDs, which only make sense for writers whose content type is EQUALITY_DELETES. Calling it on a builder configured for data files or position deletes throws UnsupportedOperationException — the builder cannot honor the setting for this writer type.

Solutions

1. Only call equalityFieldIds when building an equality-delete writer (FileContent.EQUALITY_DELETES).
2. Set the content type explicitly with content(FileContent.EQUALITY_DELETES) before configuring equality fields.
3. For position deletes, use position-delete-specific configuration (delete spec) instead.
4. Remove the equalityFieldIds call from data-file writer builders.

Example fix

// before
FileWriterBuilder.<W,D,S>create()
    .content(FileContent.DATA) // wrong: data writer
    .equalityFieldIds(1, 2)
    .build();
// after
FileWriterBuilder.<W,D,S>create()
    .content(FileContent.EQUALITY_DELETES)
    .equalityFieldIds(1, 2)
    .build();

if (builder instanceof FileWriterBuilderImpl && content != FileContent.EQUALITY_DELETES) {
  throw new IllegalArgumentException("equalityFieldIds only valid for equality-delete writers");
}

boolean supportsEqualityFields(FileContent c) { return c == FileContent.EQUALITY_DELETES; }

try {
  builder.equalityFieldIds(1, 2);
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("configure content(EQUALITY_DELETES) before equalityFieldIds", e);
}

When it happens

Trigger: Chaining .equalityFieldIds(...) on a FileWriterBuilder created for a data file or position-delete writer (FileContent.DATA or POSITION_DELETES).

Common situations: Generic writer-building code that always sets equality fields; copy-pasted builder chains reused across delete types; confusion between position deletes and equality deletes.

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

• does not implement length
• does not support forEach
• Unsupported task group for columnar reads
• Altering a view is not supported by catalog:
• Altering a view is not supported by catalog

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/formats/FileWriterBuilderImpl.java:161

    return this;
  }

  @Override
  public FileWriterBuilderImpl<W, D, S> keyMetadata(EncryptionKeyMetadata newKeyMetadata) {
    this.keyMetadata = newKeyMetadata;
    return this;
  }

  @Override
  public FileWriterBuilderImpl<W, D, S> sortOrder(SortOrder newSortOrder) {
    this.sortOrder = newSortOrder;
    return this;
  }

  @Override
  public FileWriterBuilderImpl<W, D, S> equalityFieldIds(int... fieldIds) {
    if (content != FileContent.EQUALITY_DELETES) {
      throw new UnsupportedOperationException(
          "Equality field ids not supported for this writer type");
    }

    this.equalityFieldIds = fieldIds;
    return this;
  }

  ModelWriteBuilder<D, S> modelWriteBuilder() {
    return modelWriteBuilder;
  }

  String location() {
    return location;
  }

  FileFormat format() {
    return format;
  }

View on GitHub (pinned to 86d9c8fc54)