apache/iceberg · error · IllegalArgumentException

Invalid partition data for content file: expected array or o

Error message

Invalid partition data for content file: expected array or object (%s)

What it means

When parsing a ContentFile from JSON, the partition field must be a JSON array (positional values) or object (field-id keyed values). Any other node type (string, number, null, etc.) cannot be converted into partition data, so this IllegalArgumentException is thrown with the offending node.

Source

Thrown at core/src/main/java/org/apache/iceberg/ContentFileParser.java:404

        Object partitionValue = SingleValueParser.fromJson(field.type(), partitionNode.get(pos));
        partitionData.set(pos, partitionValue);
      }
    } else if (partitionNode.isObject()) {
      // Handle partition struct object format, which serializes by field ID and skips
      // null partition values
      Preconditions.checkState(
          partitionNode.size() <= fields.size(),
          "Invalid partition data size: expected <= %s, actual = %s",
          fields.size(),
          partitionNode.size());

      StructLike structLike = (StructLike) SingleValueParser.fromJson(partitionType, partitionNode);
      for (int pos = 0; pos < partitionData.size(); ++pos) {
        Class<?> javaClass = fields.get(pos).type().typeId().javaClass();
        partitionData.set(pos, structLike.get(pos, javaClass));
      }
    } else {
      throw new IllegalArgumentException(
          String.format(
              "Invalid partition data for content file: expected array or object (%s)",
              partitionNode));
    }

    return partitionData;
  }

  private static FileContent fileContentFromJson(String content) {
    switch (content) {
      case CONTENT_DATA:
        return FileContent.DATA;
      case CONTENT_POSITION_DELETES:
        return FileContent.POSITION_DELETES;
      case CONTENT_EQUALITY_DELETES:
        return FileContent.EQUALITY_DELETES;
      default:
        // In 1.10 and before, file content is serialized as the FileContent enum value

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Emit partition data as an array of positional values or an object keyed by field ID.
2. Regenerate the JSON with Iceberg's ContentFileParser.toJson.
3. Validate the JSON shape before feeding it to fromJson.

Example fix

// before
{"partition": "2024-01-01"}
// after
{"partition": ["2024-01-01"]}

if (partitionNode != null && !partitionNode.isArray() && !partitionNode.isObject()) {
  throw new IllegalArgumentException("partition must be array or object");
}

try { ContentFileParser.fromJson(json, type); } catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("bad partition payload", e);
}

When it happens

Trigger: ContentFileParser.fromJson given a data/delete file entry whose 'partition' value is a scalar or other non-array/non-object JSON node.

Common situations: Hand-edited metadata/stats JSON; external tools emitting partition values as strings; truncated or corrupted JSON payloads.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid field ID for content stats: %s
• Invalid file content value: '%s'
• Unknown task type:
• Cannot parse default as a %s value: %s
• Cannot parse to a duration string value: %s: %s

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