apache/iceberg · error · ValidationException

Cannot apply unknown WAP ID '%s'

Error message

Cannot apply unknown WAP ID '%s'

What it means

PublishChangesProcedure looks up the staged snapshot with the given WAP ID and cherry-picks it. If no snapshot in the table carries that staged WAP ID, publishing cannot proceed and this ValidationException is thrown.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/procedures/PublishChangesProcedure.java:112

    return modifyIcebergTable(
        tableIdent,
        table -> {
          Snapshot matchingSnap = null;
          for (Snapshot snap : table.snapshots()) {
            if (wapId.equals(WapUtil.stagedWapId(snap))) {
              if (matchingSnap != null) {
                throw new ValidationException(
                    "Cannot apply non-unique WAP ID. Found multiple snapshots with WAP ID '%s'",
                    wapId);
              } else {
                matchingSnap = snap;
              }
            }
          }

          if (matchingSnap == null) {
            throw new ValidationException("Cannot apply unknown WAP ID '%s'", wapId);
          }

          long wapSnapshotId = matchingSnap.snapshotId();
          table.manageSnapshots().cherrypick(wapSnapshotId).commit();
          Snapshot currentSnapshot = table.currentSnapshot();
          InternalRow outputRow = newInternalRow(wapSnapshotId, currentSnapshot.snapshotId());
          return asScanIterator(OUTPUT_TYPE, outputRow);
        });
  }

  @Override
  public String name() {
    return NAME;
  }

  @Override
  public String description() {
    return "ApplyWapChangesProcedure";

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify staged snapshots via SELECT * FROM table.snapshots WHERE summary['wap.id'] IS NOT NULL and use an existing ID.
  2. Re-run the write job with spark.wap.id set before publishing.
  3. Check snapshot expiration settings — increase retention so staged snapshots survive until publish.

Example fix

// before
call publish_changes(table => 'db.t', wap_id => 'wap-123')
// after
-- find real id first: SELECT snapshot_id, summary['wap.id'] FROM db.t.snapshots
call publish_changes(table => 'db.t', wap_id => 'wap-abc')
Defensive patterns

Strategy: validation

Validate before calling

val staged = spark.table(s"$t.snapshots")
  .filter(col("summary.wap.id") === wapId)
require(staged.count() == 1, s"WAP ID $wapId not staged (or ambiguous)")

Try / catch

try {
  spark.sql(s"CALL cat.system.publish_changes(table => '$t', wap_id => '$id')")
} catch {
  case e: Exception if e.getMessage.contains("unknown WAP ID") =>
    logger.error("Staged snapshot missing; re-run the writer job")
}

Prevention

When it happens

Trigger: Calling publish_changes with a wap_id that matches no snapshot's staged WAP ID — e.g. the write with spark.wap.id failed, the snapshots were expired, or a wrong ID was passed.

Common situations: Typos in the WAP ID; writer job failed before committing the staged snapshot; snapshots table retained less than expected so staged snapshots were expired; forgetting to set spark.wap.id on the writer (so nothing was staged).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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