apache/iceberg · error · UnsupportedOperationException

Expected delete file to be under the source prefix: but…

Error message

Expected delete file to be under the source prefix:  but was 

What it means

Thrown by RewriteTablePathUtil.newEqualityDeleteEntry when rewriting a table's metadata at a new location: an equality delete file's location does not start with the expected source prefix, so it cannot be remapped to the target prefix. The utility can only rewrite files that lived under the original table location.

Solutions

1. Verify sourcePrefix matches the actual location prefix of all delete files in the table metadata.
2. Ensure the table being rewritten was not relocated/imported without updating its data/delete file paths; rewrite data first or use a prefix that covers all files.
3. Locate the offending delete file path (printed in the message) and manually relocate it under the source prefix or fix the metadata.

Example fix

// before
RewriteTablePathUtil.rewrite(toTable, fromTable, "s3://old-bucket/wrong-prefix", "s3://new-bucket/table");
// after
RewriteTablePathUtil.rewrite(toTable, fromTable, "s3://old-bucket/warehouse/db/table", "s3://new-bucket/table");

DeleteFile f = ...;
if (!f.location().startsWith(sourcePrefix)) {
  throw new IllegalStateException("Delete file outside source prefix: " + f.location());
}

boolean isUnderPrefix(String path, String prefix) { return path != null && prefix != null && path.startsWith(prefix); }

try { rewriteTablePath(...); } catch (UnsupportedOperationException e) { /* inspect path in message, fix sourcePrefix */ }

When it happens

Trigger: Calling RewriteTablePathUtil to rewrite table path metadata when a DeleteFile (equality delete) references a location outside sourcePrefix — e.g. the table was moved, imported from another location, or a stale/custom table location is supplied.

Common situations: Migrating a table between buckets/paths where delete files were written under an older location; supplying a wrong sourcePrefix to the rewrite utility; tables copied or registered from a different filesystem location.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Expected delete file
• Path does not start with
• ALTER VIEW AS is not supported. Use CREATE OR REPLACE VIEW…
• apply(value) is deprecated, use bind(Type).apply(value)
• apply(value) is deprecated, use bind(Type).apply(value)

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/RewriteTablePathUtil.java:611

      case ADDED:
        writer.add(file);
        break;
      case EXISTING:
        writer.existing(
            file, entry.snapshotId(), entry.dataSequenceNumber(), entry.fileSequenceNumber());
        break;
      case DELETED:
        writer.delete(file, entry.dataSequenceNumber(), entry.fileSequenceNumber());
        break;
    }
  }

  private static DeleteFile newEqualityDeleteEntry(
      DeleteFile file, PartitionSpec spec, String sourcePrefix, String targetPrefix) {
    String path = file.location();

    if (!path.startsWith(sourcePrefix)) {
      throw new UnsupportedOperationException(
          "Expected delete file to be under the source prefix: "
              + sourcePrefix
              + " but was "
              + path);
    }
    int[] equalityFieldIds = file.equalityFieldIds().stream().mapToInt(Integer::intValue).toArray();
    String newPath = newPath(path, sourcePrefix, targetPrefix);
    return FileMetadata.deleteFileBuilder(spec)
        .ofEqualityDeletes(equalityFieldIds)
        .copy(file)
        .withPath(newPath)
        .withSplitOffsets(file.splitOffsets())
        .build();
  }

  private static DeleteFile newPositionDeleteEntry(
      DeleteFile file,
      PartitionSpec spec,

View on GitHub (pinned to 86d9c8fc54)