apache/iceberg · error · IllegalArgumentException

Unexpected null order: ${nullOrderingAsString}

Error message

Unexpected null order: ${nullOrderingAsString}

What it means

SortOrderParser.toNullOrder throws IllegalArgumentException when the JSON string for a sort order's null ordering is not "nulls-first" or "nulls-last" (case-insensitive). This happens while parsing table metadata's sort-order JSON. It signals malformed or spec-violating metadata rather than a caller mistake.

Source

Thrown at core/src/main/java/org/apache/iceberg/SortOrderParser.java:177

      String directionAsString = JsonUtil.getString(DIRECTION, element);
      SortDirection direction = SortDirection.fromString(directionAsString);

      String nullOrderingAsString = JsonUtil.getString(NULL_ORDER, element);
      NullOrder nullOrder = toNullOrder(nullOrderingAsString);

      builder.addSortField(transform, sourceId, direction, nullOrder);
    }
  }

  private static NullOrder toNullOrder(String nullOrderingAsString) {
    switch (nullOrderingAsString.toLowerCase(Locale.ROOT)) {
      case "nulls-first":
        return NULLS_FIRST;
      case "nulls-last":
        return NULLS_LAST;
      default:
        throw new IllegalArgumentException("Unexpected null order: " + nullOrderingAsString);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the table metadata JSON (metadata file's sort-order array) and correct the null-order field to exactly "nulls-first" or "nulls-last".
2. Regenerate the metadata by rewriting the table's sort order, e.g. table.updateSortOrder().asc("col").commit(), so a conformant parser writes the field.
3. If the metadata came from another tool, fix that tool's serializer to emit the spec-defined strings.
4. Restore the metadata file from a prior valid snapshot if it was hand-edited or corrupted.

Example fix

// before (metadata JSON)
{"sort-order-id": 1, "fields": [...], "null-order": "NULLS_FIRST"}

// after (metadata JSON)
{"sort-order-id": 1, "fields": [...], "null-order": "nulls-first"}

// Java: validate before/while parsing metadata
String nullOrder = sortOrderJson.get("null-order").textValue();
if (!"nulls-first".equalsIgnoreCase(nullOrder) && !"nulls-last".equalsIgnoreCase(nullOrder)) {
  throw new IllegalArgumentException("Bad null-order in metadata: " + nullOrder);
}

// Java
try {
  TableMetadata meta = TableMetadataParser.read(io, metadataLocation);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Unexpected null order")) {
    // fall back to previous valid metadata file or repair sort-order JSON
  } else { throw e; }
}

When it happens

Trigger: Reading table metadata (TableMetadataParser -> SortOrderParser.fromJson -> nullOrder) whose sort-order JSON contains a "null-order" value other than nulls-first/nulls-last — e.g. hand-edited metadata, a null/missing value serialized as the string "null", or metadata from a non-conformant writer.

Common situations: Hand-edited or truncated metadata JSON files; third-party catalog implementations writing non-conformant sort-order JSON; typos like "nullfirst" or "NULLS_FIRST" with underscore; migrating metadata from tools that emit wrong casing handled incorrectly.

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

• String.format("Invalid snapshot ref type: %s", snapshotRefTy
• Failed to read file: %s
• Requirement failed: default sort order changed: expected id
• Failed to parse Spark view dependencies
• Encountered invalid summary for snapshot {}: the field 'oper

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