apache/iceberg · error · UnsupportedOperationException

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

Error message

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

What it means

equalSchemes(Map<String,String>) on DeleteOrphanFiles declares which URI schemes should be treated as equal (e.g., "s3" vs "s3a") during orphan file detection. The default method throws UnsupportedOperationException because the concrete action implementation does not support this configuration.

Solutions

Upgrade the engine integration to a version implementing equalSchemes.
Drop the equalSchemes call and rely on the default scheme comparison if no aliases must be treated equal.
Override equalSchemes in a custom DeleteOrphanFiles implementation.

Example fix

// before
DeleteOrphanFiles a = action.equalSchemes(Map.of("s3", "s3a")); // throws
// after (upgrade, or remove configuration)
DeleteOrphanFiles a = action; // default scheme handling

Defensive patterns

Strategy: try-catch

Validate before calling

boolean ok = Arrays.stream(action.getClass().getMethods()).anyMatch(m -> "equalSchemes".equals(m.getName()) && m.getDeclaringClass() != DeleteOrphanFiles.class);

Type guard

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

Try / catch

try { action = action.equalSchemes(Map.of("s3", "s3a")); } catch (UnsupportedOperationException e) { LOG.warn("equalSchemes unsupported; using default comparison"); }

Prevention

Upgrade before using scheme normalization features
Avoid scheme aliases in storage locations so equalSchemes is unnecessary

When it happens

Trigger: Calling .equalSchemes(map) on a DeleteOrphanFiles implementation that has not overridden the method — typically older engine runtimes or custom action implementations.

Common situations: Normalizing scheme aliases after a storage migration (s3 vs s3a vs s3n) while on a runtime without scheme-equality support; following current documentation against an older Iceberg build.

Related errors

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

Appendix: source

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

   * @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");
  }

  /**
   * Passes authorities that should be considered equal.
   *
   * <p>The key may include a comma-separate list of authorities. For instance, Map("s1name,s2name",
   * "servicename").
   *
   * @param newEqualAuthorities list of equal authorities
   * @return this for method chaining
   */
  default DeleteOrphanFiles equalAuthorities(Map<String, String> newEqualAuthorities) {
    throw new UnsupportedOperationException(
        this.getClass().getName() + " does not implement equalAuthorities");
  }

  /** The action result that contains a summary of the execution. */

View on GitHub (pinned to 86d9c8fc54)