apache/iceberg · error · NoSuchTableException

Table does not exist at location

Error message

Table does not exist at location: %s

What it means

HadoopTables.load() throws NoSuchTableException when newTableOps(location).current() returns null, meaning no table metadata (no version-hint/first metadata file) exists at the given location. Iceberg distinguishes 'path exists but not a table' from load failures — this is the not-a-table/absent-table signal.

Solutions

1. Verify the location contains metadata/version-hint.text (hdfs dfs -ls <loc>/metadata)
2. Correct the path to the table root, not a data or partition subdirectory
3. Recreate the table if it was dropped
4. Use catalog.loadTable() instead of raw path loading to avoid path mistakes

Example fix

// before
Table t = tables.load("hdfs://ns/warehouse/db/table/data");
// after
Table t = tables.load("hdfs://ns/warehouse/db/table"); // root with metadata/

boolean isTable = fs.exists(new Path(location, "metadata/version-hint.text"));
if (!isTable) throw new IllegalArgumentException("not an Iceberg table: " + location);

try { return tables.load(location); } catch (NoSuchTableException e) { return null; /* or create default */ }

When it happens

Trigger: load() with a path that has no Iceberg metadata under it; typo in the table path; the table was dropped; pointing at the table's data directory instead of its root (or vice versa).

Common situations: Hardcoded HDFS paths after a table rename/move; loading a path before table creation completes; using Spark output directory (data files only) as the table location; case-sensitivity or trailing-slash mistakes in the path.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Cannot pass path based identifier to
• Cannot pass path based identifier to
• Cannot pass path based identifier to
• Cannot remove properties " + namespace + " …
• Cannot rename because the table does not exist in Glue

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/HadoopTables.java:95

   *
   * @param location a path URI (e.g. hdfs:///warehouse/my_table/)
   * @return table implementation
   */
  @Override
  public Table load(String location) {
    Table result;
    Pair<String, MetadataTableType> parsedMetadataType = parseMetadataType(location);

    if (parsedMetadataType != null) {
      // Load a metadata table
      result = loadMetadataTable(parsedMetadataType.first(), location, parsedMetadataType.second());
    } else {
      // Load a normal table
      TableOperations ops = newTableOps(location);
      if (ops.current() != null) {
        result = new BaseTable(ops, location);
      } else {
        throw new NoSuchTableException("Table does not exist at location: %s", location);
      }
    }

    LOG.info("Table location loaded: {}", result.location());
    return result;
  }

  @Override
  public boolean exists(String location) {
    return newTableOps(location).current() != null;
  }

  /**
   * Try to resolve a metadata table, which we encode as URI fragments e.g.
   * hdfs:///warehouse/my_table#snapshots
   *
   * @param location Path to parse
   * @return A base table name and MetadataTableType if a type is found, null if not

View on GitHub (pinned to 86d9c8fc54)