apache/beam · error · IllegalStateException

SortOrder with id not found in sortOrders map

Error message

SortOrder with id {} not found in sortOrders map

What it means

SerializableTableSpec.getSortOrder() looks up the stored orderId in the serialized sortOrders map and throws IllegalStateException when it is missing. The map snapshots the table's sort orders at serialization time; a miss indicates incomplete/inconsistent serialized state or a sort order that no longer exists in the table.

Solutions

  1. Rebuild via SerializableTableSpec.from(table) so sortOrders comes from the table's current sort orders.
  2. Check the table's sortOrders map for the stored order id; fall back to the current sort order if it was replaced.
  3. Refresh the table and re-serialize after any sort order change.
  4. If unsorted (order id 0) is acceptable, treat it explicitly instead of relying on lookup.

Example fix

// before
long orderId = spec.getOrderId(); // replaced order, no longer in map
SortOrder so = spec.getSortOrder();
// after
SerializableTableSpec spec = SerializableTableSpec.from(table); // rebuild snapshot before reading sort order
Defensive patterns

Strategy: validation

Validate before calling

SortOrder so = spec.getSortOrders().get(spec.getOrderId());
if (so == null) {
  // sort order replaced — rebuild snapshot from the table
  spec = SerializableTableSpec.from(table);
}

Try / catch

try {
  SortOrder so = spec.getSortOrder();
} catch (IllegalStateException e) {
  // fall back to table.sortOrder() current order
}

Prevention

When it happens

Trigger: Calling getSortOrder() when sortOrders lacks the entry for getOrderId() — e.g. the sort order was replaced after serialization, or the object was built without populating sortOrders.

Common situations: Sort order replaced via table.replaceSortOrder() between snapshot and use; stale checkpointed state; hand-constructed SerializableTableSpec in tests or tooling that omitted sort orders.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/6c9f5d537f6ad064. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/SerializableTableSpec.java:201

      synchronized (this) {
        local = cachedSortOrders;
        if (local == null) {
          ImmutableMap.Builder<Integer, SortOrder> builder = ImmutableMap.builder();
          for (Map.Entry<Integer, String> entry : getSortOrdersJson().entrySet()) {
            builder.put(entry.getKey(), SortOrderParser.fromJson(getSchema(), entry.getValue()));
          }
          cachedSortOrders = local = builder.build();
        }
      }
    }
    return local;
  }

  @SchemaIgnore
  public SortOrder getSortOrder() {
    SortOrder order = getSortOrders().get(getOrderId());
    if (order == null) {
      throw new IllegalStateException(
          "SortOrder with id " + getOrderId() + " not found in sortOrders map");
    }
    return order;
  }

  @SchemaIgnore
  public @Nullable SortOrder getSortOrder(int orderId) {
    return getSortOrders().get(orderId);
  }

  @SchemaIgnore
  public TableIdentifier getTableIdentifier() {
    TableIdentifier local = cachedTableIdentifier;
    if (local == null) {
      synchronized (this) {
        local = cachedTableIdentifier;
        if (local == null) {
          cachedTableIdentifier =

View on GitHub (pinned to 12126d8942)