apache/iceberg · error · UnsupportedOperationException

this.getClass().getName() + " does not implement…

Error message

this.getClass().getName() + " does not implement prefixMismatchMode"

What it means

DeleteOrphanFiles is an action interface whose fluent configuration methods are defaults that throw UnsupportedOperationException. prefixMismatchMode(PrefixMismatchMode) sets how URI prefix mismatches (scheme/authority differences) are handled during orphan file deletion; an action implementation that has not overridden it throws instead of returning the configured action.

Solutions

  1. Upgrade the engine integration (e.g., iceberg-spark) to a version whose DeleteOrphanFiles implementation supports prefixMismatchMode.
  2. Remove the prefixMismatchMode call if the runtime does not need prefix mismatch handling (default mode ignores/none).
  3. If implementing a custom DeleteOrphanFiles action, override prefixMismatchMode to store and honor the mode.

Example fix

// before
DeleteOrphanFiles a = actions.deleteOrphanFiles(table).prefixMismatchMode(PrefixMismatchMode.REMOVE); // throws on old impl
// after (guard by version/capability, or upgrade)
DeleteOrphanFiles a = SparkActions.get().deleteOrphanFiles(table).prefixMismatchMode(PrefixMismatchMode.REMOVE);
Defensive patterns

Strategy: try-catch

Validate before calling

// upgrade check: ensure the action impl overrides prefixMismatchMode
boolean ok = Arrays.stream(deleteOrphanFiles.getClass().getMethods()).anyMatch(m -> "prefixMismatchMode".equals(m.getName()) && m.getDeclaringClass() != DeleteOrphanFiles.class);

Type guard

boolean implemented = deleteOrphanFiles.getClass() != DeleteOrphanFiles.class;

Try / catch

try { action = action.prefixMismatchMode(PrefixMismatchMode.REMOVE); } catch (UnsupportedOperationException e) { action = action; /* proceed with default mode */ }

Prevention

When it happens

Trigger: Calling deleteOrphanFiles().prefixMismatchMode(...) on an action implementation (e.g., from an older Spark/Flink version or a custom action) that does not override prefixMismatchMode.

Common situations: Configuring prefix handling for object-store migrations (S3 to GCS, scheme/authority normalization) while running an older Iceberg engine runtime where the option was not yet implemented; copying config code from newer examples onto an older dependency.

Related errors

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

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/actions/DeleteOrphanFiles.java:109

   * metadata references files that match listed/provided files except for authority/scheme.
   *
   * <p>Possible values are "ERROR", "IGNORE", "DELETE". The default mismatch mode is "ERROR", which
   * means an exception is thrown whenever there is a mismatch in authority/scheme. It's the
   * recommended mismatch mode and should be changed only in some rare circumstances. If there is a
   * mismatch, use {@link #equalSchemes(Map)} and {@link #equalAuthorities(Map)} to resolve
   * conflicts by providing equivalent schemes and authorities. If it is impossible to determine
   * whether the conflicting authorities/schemes are equal, set the prefix mismatch mode to "IGNORE"
   * to skip files with mismatches. If you have manually inspected all conflicting
   * authorities/schemes, provided equivalent schemes/authorities and are absolutely confident the
   * remaining ones are different, set the prefix mismatch mode to "DELETE" to consider files with
   * mismatches as orphan. It will be impossible to recover files after deletion, so the "DELETE"
   * prefix mismatch mode must be used with extreme caution.
   *
   * @param newPrefixMismatchMode mode for handling prefix mismatches
   * @return this for method chaining
   */
  default DeleteOrphanFiles prefixMismatchMode(PrefixMismatchMode newPrefixMismatchMode) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " does not implement prefixMismatchMode");
  }

  /**
   * Passes schemes that should be considered equal.
   *
   * <p>The key may include a comma-separated list of schemes. For instance, Map("s3a,s3,s3n",
   * "s3").
   *
   * @param newEqualSchemes list of equal schemes
   * @return this for method chaining
   */
  default DeleteOrphanFiles equalSchemes(Map<String, String> newEqualSchemes) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " does not implement equalSchemes");
  }

  /**

View on GitHub (pinned to 86d9c8fc54)