apache/iceberg · error · IllegalStateException

Unknown content type

Error message

Unknown content type 

What it means

FileMetadata.Builder.build only handles POSITION_DELETES, EQUALITY_DELETES (and DV-equivalent) content types when defaulting sortOrderId; a content type it does not recognize reaches the default branch and throws IllegalStateException('Unknown content type ' + content). This means the builder was handed a FileContent value that is not a supported delete content type — e.g. DATA (0) passed to a delete-file builder.

Solutions

1. Ensure the delete builder's content is set explicitly withContent(FileContent.POSITION_DELETES) or EQUALITY_DELETES and never copied from a data file.
2. If reading manifests produced by a newer Iceberg, upgrade the reader to a version that supports the new FileContent value.
3. Check custom writers/metadata repair scripts for default content values (DATA=0) leaking into delete-file builders.

Example fix

// before: content copied from a data file
deleteBuilder.withContent(dataFile.content()).withPath(...); // DATA -> throws
// after: set the delete content type explicitly
deleteBuilder.withContent(FileContent.POSITION_DELETES).withPath(...);

Preconditions.checkArgument(
    content == FileContent.POSITION_DELETES || content == FileContent.EQUALITY_DELETES,
    "Delete builder requires a delete content type, got: %s", content);

boolean isDeleteContent(FileContent c) {
  return c == FileContent.POSITION_DELETES || c == FileContent.EQUALITY_DELETES;
}

try {
  DeleteFile df = builder.build();
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unknown content type")) {
    // fix the builder call: set withContent(POSITION_DELETES | EQUALITY_DELETES)
  } else throw e;
}

When it happens

Trigger: Calling FileMetadata.deleteBuilder(spec).withContent(...) with an unsupported/legacy content enum value, or build() invoked with content left as DATA/null in a delete builder after a code path forgot to set the content type.

Common situations: Custom metadata generators/repair tools writing manifest entries directly; copy code that copies a data file's content type into a delete builder; reading manifests written by a newer spec with unknown FileContent values using an older Iceberg reader.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot apply unknown unique constraint:
• Cannot apply unknown unique constraint:
• Cannot build StorageCredential, some of required attributes…
• Cannot process unknown snapshot operation
• Cannot read unknown manifest type

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/FileMetadata.java:289

            referencedDataFile != null, "Referenced data file is required for DV");
      } else {
        Preconditions.checkArgument(contentOffset == null, "Content offset can only be set for DV");
        Preconditions.checkArgument(
            contentSizeInBytes == null, "Content size can only be set for DV");
      }

      switch (content) {
        case POSITION_DELETES:
          Preconditions.checkArgument(
              sortOrderId == null, "Position delete file should not have sort order");
          break;
        case EQUALITY_DELETES:
          if (sortOrderId == null) {
            sortOrderId = SortOrder.unsorted().orderId();
          }
          break;
        default:
          throw new IllegalStateException("Unknown content type " + content);
      }

      return new GenericDeleteFile(
          specId,
          content,
          filePath,
          format,
          isPartitioned ? DataFiles.copy(spec, partitionData) : null,
          fileSizeInBytes,
          new Metrics(
              recordCount,
              columnSizes,
              valueCounts,
              nullValueCounts,
              nanValueCounts,
              lowerBounds,
              upperBounds,
              avgValueSizes,

View on GitHub (pinned to 86d9c8fc54)