apache/iceberg · error · IllegalArgumentException

Unknown comparison result

Error message

Unknown comparison result

What it means

TableUpdater.findOrCreateSchema compares the table's current schema with the target schema and switches on the comparison result (equal / evolved / incompatible). The default branch is reached only when the comparison helper returns an unexpected value, so this IllegalArgumentException signals an internal invariant violation rather than user error.

Source

Thrown at flink/v1.20/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 this as a bug to the Iceberg project with the full stack trace and table schema details
2. Retry the job; if the cause was a transient concurrent schema update, re-running against the committed schema may succeed
3. Check the Iceberg version for known fixes in TableUpdater schema-comparison handling and upgrade
4. Capture the current table schema and the DataStream schema being applied to help reproduce and diagnose

try {
  updater.newSchemaInfo(identifier, schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Unknown comparison result")) {
    // log full context, retry with fresh table metadata or report bug
  }
  throw e;
}

When it happens

Trigger: The schema-comparison logic in TableUpdater returns a value outside the enumerated cases (equal, needs-update) during findOrCreateSchema, called from newSchemaInfo while syncing a DataStream schema to the Iceberg table schema.

Common situations: Practically unreachable for users; would appear after an internal code change to the comparison helper or cache behavior, or concurrent schema updates racing with the updater so an unexpected branch result is produced.

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
• The configured equality field column IDs {} are not matched
• Field + field.name() + not found in source schema
• Provided schema:...Problems: (IllegalArgumentException with
• Cannot delete value type from map:

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