apache/iceberg · error · UnsupportedOperationException

Cannot apply unknown unique constraint:

Error message

Cannot apply unknown unique constraint: 

What it means

The default branch of the constraint-type switch fires when UniqueConstraint.getType() returns a value other than PRIMARY_KEY or UNIQUE_KEY — an unknown/unrecognized constraint type enum. It guards against new or foreign constraint types reaching Iceberg's Flink alter logic.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/util/FlinkAlterTableUtil.java:256

      TableChange.After after = (TableChange.After) newPosition;
      pendingUpdate.moveAfter(modifyColumnPosition.getOldColumn().getName(), after.column());
    } else {
      throw new UnsupportedOperationException(
          "Cannot apply unknown modify-column-position change: " + modifyColumnPosition);
    }
  }

  private static void applyUniqueConstraint(
      UpdateSchema pendingUpdate, UniqueConstraint constraint) {
    switch (constraint.getType()) {
      case PRIMARY_KEY:
        pendingUpdate.setIdentifierFields(constraint.getColumns());
        break;
      case UNIQUE_KEY:
        throw new UnsupportedOperationException(
            "Unsupported table change: setting unique key constraints.");
      default:
        throw new UnsupportedOperationException(
            "Cannot apply unknown unique constraint: " + constraint.getType().name());
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Align Flink and iceberg-flink-runtime versions so enum values match
2. Log constraint.getType().name() and confirm which value is being sent
3. Extend/handle the new type in a patched applyUniqueConstraint if it must be supported

Example fix

// before
UnsupportedOperationException: Cannot apply unknown unique constraint: SOME_NEW_TYPE
// after
if (constraint.getType() == ConstraintType.PRIMARY_KEY
    || constraint.getType() == ConstraintType.UNIQUE_KEY) {
  applyUniqueConstraint(update, constraint);
}

ConstraintType t = constraint.getType();
if (t != ConstraintType.PRIMARY_KEY && t != ConstraintType.UNIQUE_KEY) {
  throw new IllegalArgumentException("Unknown constraint type: " + t);
}

static boolean isKnownConstraintType(UniqueConstraint c) {
  switch (c.getType()) {
    case PRIMARY_KEY:
    case UNIQUE_KEY: return true;
    default: return false;
  }
}

try { FlinkAlterTableUtil.applySchemaChanges(update, changes); }
catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Cannot apply unknown unique constraint")) { log.error("Constraint type mismatch; check versions"); }
  throw e;
}

When it happens

Trigger: A UniqueConstraint instance with a non-standard/unknown ConstraintType passed into applySchemaChanges (custom Flink fork, version skew adding new enum constants).

Common situations: Flink or iceberg-flink version mismatch introducing new constraint enum constants; custom catalog implementations synthesizing constraint objects.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported file content type: ${file.content()}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• Cannot apply unknown unique constraint:
• Unsupported table change: DropConstraint.

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