apache/iceberg · error · IllegalArgumentException

Unknown comparison result

Error message

Unknown comparison result

What it means

In TableUpdater.findOrCreateSchema, after comparing the current table schema against the target schema, a switch on the comparison result has a default branch indicating an impossible outcome of the internal comparison logic. Reaching it means the internal comparison produced an unexpected value — a defensive invariant check, not user input validation.

Source

Thrown at flink/v2.1/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. Retry the write/job; transient concurrent-modification races may resolve on retry.
2. File a bug against the Iceberg Flink connector with the stack trace.
3. Upgrade to the latest connector version where the comparison switch may be fixed.

try {
  schema = tableUpdater.findOrCreateSchema(identifier, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().equals("Unknown comparison result")) {
    // transient internal race — retry once, then report
  } else throw e;
}

When it happens

Trigger: Internal bug or unexpected schema comparison state while evolving a schema via newSchemaInfo; virtually impossible to trigger from user code except through a race where the table schema changes concurrently and the comparison result enumeration is extended without updating the switch.

Common situations: Hitting it during concurrent schema evolution races in Flink writing jobs that auto-evolve schemas; typically indicates a connector bug to report.

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

• Unknown comparison result
• 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.

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