{"record":{"id":"42b028bf346c582b","repo":"apache/iceberg","slug":"unexpected-null-order-nullorderingasstring","errorCode":null,"errorMessage":"Unexpected null order: ${nullOrderingAsString}","messagePattern":"Unexpected null order: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/SortOrderParser.java","lineNumber":177,"sourceCode":"\n      String directionAsString = JsonUtil.getString(DIRECTION, element);\n      SortDirection direction = SortDirection.fromString(directionAsString);\n\n      String nullOrderingAsString = JsonUtil.getString(NULL_ORDER, element);\n      NullOrder nullOrder = toNullOrder(nullOrderingAsString);\n\n      builder.addSortField(transform, sourceId, direction, nullOrder);\n    }\n  }\n\n  private static NullOrder toNullOrder(String nullOrderingAsString) {\n    switch (nullOrderingAsString.toLowerCase(Locale.ROOT)) {\n      case \"nulls-first\":\n        return NULLS_FIRST;\n      case \"nulls-last\":\n        return NULLS_LAST;\n      default:\n        throw new IllegalArgumentException(\"Unexpected null order: \" + nullOrderingAsString);\n    }\n  }\n}\n","sourceCodeStart":159,"sourceCodeEnd":181,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/SortOrderParser.java#L159-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the table metadata JSON (metadata file's sort-order array) and correct the null-order field to exactly \"nulls-first\" or \"nulls-last\".","Regenerate the metadata by rewriting the table's sort order, e.g. table.updateSortOrder().asc(\"col\").commit(), so a conformant parser writes the field.","If the metadata came from another tool, fix that tool's serializer to emit the spec-defined strings.","Restore the metadata file from a prior valid snapshot if it was hand-edited or corrupted."],"exampleFix":"// before (metadata JSON)\n{\"sort-order-id\": 1, \"fields\": [...], \"null-order\": \"NULLS_FIRST\"}\n\n// after (metadata JSON)\n{\"sort-order-id\": 1, \"fields\": [...], \"null-order\": \"nulls-first\"}","handlingStrategy":"validation","validationCode":"// Java: validate before/while parsing metadata\nString nullOrder = sortOrderJson.get(\"null-order\").textValue();\nif (!\"nulls-first\".equalsIgnoreCase(nullOrder) && !\"nulls-last\".equalsIgnoreCase(nullOrder)) {\n  throw new IllegalArgumentException(\"Bad null-order in metadata: \" + nullOrder);\n}","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n  TableMetadata meta = TableMetadataParser.read(io, metadataLocation);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Unexpected null order\")) {\n    // fall back to previous valid metadata file or repair sort-order JSON\n  } else { throw e; }\n}","preventionTips":["Never hand-edit table metadata JSON; use table.updateSortOrder() to change sort orders.","Restore metadata files from backups if corruption is suspected.","Ensure any third-party serializer of Iceberg metadata emits the exact strings nulls-first/nulls-last."],"tags":["metadata","parsing","sort-order","iceberg"],"backgroundTag":"invalid-enum-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}