apache/iceberg · error · IllegalArgumentException

Unknown file content

Error message

Unknown file content: <content>

What it means

ParquetFormatModel.build() configures a Parquet write appender based on the file content type (DATA, POSITION_DELETES, EQUALITY_DELETES). If the supplied FileContent value is not one of the recognized kinds, the switch's default branch throws this IllegalArgumentException. It means the caller requested an unsupported/unrecognized file content type.

Solutions

1. Set the write builder's content to a supported FileContent (DATA, POSITION_DELETES, EQUALITY_DELETES)
2. Verify the FileContent constant comes from the same Iceberg version as the writer code
3. Check how the content value is derived (e.g. from a manifest entry) for corruption or version skew

Example fix

// before
WriteBuilder b = formatModel.write(input).content(FileContent.ENTRY_UNKNOWN);
// after
WriteBuilder b = formatModel.write(input).content(FileContent.DATA);

if (content != FileContent.DATA && content != FileContent.POSITION_DELETES
    && content != FileContent.EQUALITY_DELETES) {
  throw new IllegalArgumentException("Unsupported file content: " + content);
}

try {
  writer = formatModel.write(input).content(content).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown file content")) { /* fix content constant */ }
  throw e;
}

When it happens

Trigger: Calling build() on a WriteBuilder whose file content was set to a value outside DATA/POSITION_DELETES/EQUALITY_DELETES — e.g. an unknown enum ordinal, a corrupted descriptor, or a content type added by a newer spec but not handled here.

Common situations: Custom or newer-spec file content constants used with an older Iceberg build; misconfigured delete-file writers passing the wrong FileContent.

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

• Failed to create shredded variant writer
• Not a boolean column
• Not an binary column
• Not an double column
• Not an float column

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetFormatModel.java:277

              schema == null,
              "Invalid schema: %s. Position deletes with schema are not supported by the API.",
              schema);
          Preconditions.checkState(
              engineSchema == null,
              "Invalid engineSchema: %s. Position deletes with schema are not supported by the API.",
              engineSchema);

          internal.createContextFunc(Parquet.WriteBuilder.Context::deleteContext);
          internal.createWriterFunc(
              (icebergSchema, messageType) ->
                  new ParquetValueWriters.PositionDeleteStructWriter<D>(
                      (ParquetValueWriters.StructWriter<?>)
                          GenericParquetWriter.create(icebergSchema, messageType),
                      Function.identity()));
          internal.schema(DeleteSchemaUtil.pathPosSchema());
          break;
        default:
          throw new IllegalArgumentException("Unknown file content: " + content);
      }

      if (shredVariants) {
        return buildShreddedAppender();
      }

      return internal.build();
    }

    /**
     * Creates a {@link BufferedFileAppender} that buffers the first N rows, runs variant shredding
     * analysis on them, then creates the real Parquet appender with a shredded schema.
     *
     * <p>Only top-level variant columns are shredded. Nested variants (inside structs/lists/maps)
     * fall through to unshredded 2-field layout because column index resolution only applies to
     * top-level fields.
     */
    private FileAppender<D> buildShreddedAppender() {

View on GitHub (pinned to 86d9c8fc54)