apache/iceberg · warning

Failed to delete file

Error message

Failed to delete {} file {}

What it means

A WARN logged by the sequential single-file deleteFile helper: io.deleteFile(file) threw a RuntimeException, so this one file was not deleted while the surrounding operation (dropTableData, dropViewMetadata, deleteFiles) continues. The file remains in storage as an orphan. Deletion during drop is deliberately best-effort so a single bad file never blocks the drop.

Solutions

1. Locate the file path in the log entry and delete it manually or via orphan-file cleanup.
2. Re-run drop/cleanup to catch remaining files.
3. Verify credentials/policies allow deletes on the affected prefix.
4. Retry during a quieter window if throttling is implicated.

Example fix

// before
catalog.dropTable(identifier); // some files failed to delete
// after
boolean exists = catalog.tableExists(identifier);
if (!exists) { SparkActions.get().deleteOrphanFiles(spark, tableLocation).execute(); }

try { catalog.dropTable(id); } catch (RuntimeException e) { /* drop continues anyway; run cleanup */ } finally { runOrphanCleanup(tableLocation); }

When it happens

Trigger: deleteFiles called with concurrent=false on a non-bulk FileIO, or dropTableData/dropViewMetadata cleanup paths; the individual delete throws — object missing due to concurrent cleanup, permission denied, network error, or a filesystem quirk (non-empty directory on HDFS local).

Common situations: Two cleanup jobs racing on the same table; restrictive bucket policies on data vs metadata prefixes; transient cloud SDK errors during large drops.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to delete file
• Cannot remove orphan files with an interval less than 24…
• Cannot remove orphan files with an interval less than 24…
• Cannot remove orphan files with an interval less than 24…
• Could not list sub directories, reached maximum depth:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/CatalogUtil.java:254

        files.forEach(file -> deleteFile(io, file, type));
      }
    }
  }

  private static void concurrentlyDeleteFiles(FileIO io, Iterable<String> files, String type) {
    Tasks.foreach(files)
        .executeWith(ThreadPools.getWorkerPool())
        .noRetry()
        .suppressFailureWhenFinished()
        .onFailure((file, exc) -> LOG.warn("Failed to delete {} file: {}", type, file, exc))
        .run(io::deleteFile);
  }

  private static void deleteFile(FileIO io, String file, String type) {
    try {
      io.deleteFile(file);
    } catch (RuntimeException e) {
      LOG.warn("Failed to delete {} file {}", type, file, e);
    }
  }

  /**
   * Load a custom catalog implementation.
   *
   * <p>The catalog must have a no-arg constructor. If the class implements Configurable, a Hadoop
   * config will be passed using Configurable.setConf. {@link Catalog#initialize(String catalogName,
   * Map options)} is called to complete the initialization.
   *
   * @param impl catalog implementation full class name
   * @param catalogName catalog name
   * @param properties catalog properties
   * @param hadoopConf hadoop configuration if needed
   * @return initialized catalog object
   * @throws IllegalArgumentException if no-arg constructor not found or error during initialization
   */
  public static Catalog loadCatalog(

View on GitHub (pinned to 86d9c8fc54)