apache/iceberg · error · IllegalArgumentException

Unknown comparison result

Error message

Unknown comparison result

What it means

TableUpdater.findOrCreateSchema compares the target schema against existing table schemas and acts on the comparison result. If the comparison yields a result outside the expected set of SchemaUpdate outcomes, the default branch throws IllegalArgumentException('Unknown comparison result') as an internal invariant guard.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/TableUpdater.java:174

            TableMetadataCache.ResolvedSchemaInfo comparisonAfterMigration =
                cache.schema(identifier, schema);
            Schema newSchema = comparisonAfterMigration.resolvedTableSchema();
            LOG.info("Table {} schema updated from {} to {}", identifier, tableSchema, newSchema);
            return comparisonAfterMigration;
          } catch (CommitFailedException e) {
            cache.invalidate(identifier);
            TableMetadataCache.ResolvedSchemaInfo newSchema = cache.schema(identifier, schema);
            if (newSchema.compareResult() != CompareSchemasVisitor.Result.SCHEMA_UPDATE_NEEDED) {
              LOG.debug("Table {} schema updated concurrently to {}", identifier, schema);
              return newSchema;
            } else {
              LOG.error(
                  "Schema update failed for {} from {} to {}", identifier, tableSchema, schema, e);
              throw e;
            }
          }
        default:
          throw new IllegalArgumentException("Unknown comparison result");
      }
    }
  }

  private PartitionSpec findOrCreateSpec(TableIdentifier identifier, PartitionSpec targetSpec) {
    PartitionSpec currentSpec = cache.spec(identifier, targetSpec);
    if (currentSpec != null) {
      return currentSpec;
    }

    Table table = catalog.loadTable(identifier);
    currentSpec = table.spec();

    PartitionSpecEvolution.PartitionSpecChanges result =
        PartitionSpecEvolution.evolve(currentSpec, targetSpec);
    if (result.isEmpty()) {
      LOG.info("Returning equivalent existing spec {} for {}", currentSpec, targetSpec);
      return currentSpec;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Report/inspect the comparison logic producing the unexpected result
2. Upgrade to a version where the switch is exhaustive over comparison results
3. If custom comparison code is involved, ensure it only returns recognized result values

try {
  tableUpdater.findOrCreateSchema(identifier, targetSchema);
} catch (IllegalArgumentException e) {
  LOG.error("Unexpected schema comparison result; check Iceberg version compatibility", e);
}

When it happens

Trigger: An unexpected SchemaComparator/comparison result value returned during schema synchronization — typically only reachable if the comparison logic is extended without updating this switch.

Common situations: Internal invariant breach after library upgrades or custom comparator implementations; not normally triggered by user configuration.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Invalid primary key '%s'. A primary key must not contain dup
• Invalid primary key '%s'. Column '%s' does not exist.
• Invalid primary key '%s'. Column '%s' is not a physical colu
• Invalid primary key '%s'. Column '%s' is nullable.
• Unsupported ZonedTimestampType.

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