apache/iceberg · error · NoSuchTableException

No such table: %s

Error message

No such table: %s

What it means

HadoopTables throws NoSuchTableException from replaceTransaction when the table does not exist at the location and orCreate is false. A replacement requires an existing table to replace. Callers wanting create-or-replace semantics should use createOrReplaceTransaction instead.

Source

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

      Map<String, String> properties = propertiesBuilder.build();
      TableMetadata metadata = tableMetadata(schema, spec, null, properties, location);
      return Transactions.createTableTransaction(location, ops, metadata);
    }

    @Override
    public Transaction replaceTransaction() {
      return newReplaceTableTransaction(false);
    }

    @Override
    public Transaction createOrReplaceTransaction() {
      return newReplaceTableTransaction(true);
    }

    private Transaction newReplaceTableTransaction(boolean orCreate) {
      TableOperations ops = newTableOps(location);
      if (!orCreate && ops.current() == null) {
        throw new NoSuchTableException("No such table: %s", location);
      }

      Map<String, String> properties = propertiesBuilder.build();
      TableMetadata metadata;
      if (ops.current() != null) {
        metadata = ops.current().buildReplacement(schema, spec, sortOrder, location, properties);
      } else {
        metadata = tableMetadata(schema, spec, sortOrder, properties, location);
      }

      if (orCreate) {
        return Transactions.createOrReplaceTableTransaction(location, ops, metadata);
      } else {
        return Transactions.replaceTableTransaction(location, ops, metadata);
      }
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the table exists with tables.exists(location) before replacing
2. Use createOrReplaceTransaction(...) if create-if-missing semantics are wanted
3. Correct the table location string
4. Create the table first if it genuinely does not exist

Example fix

// before
Transaction tx = tables.replaceTransaction(schema, spec, props, location);
// after
Transaction tx = tables.createOrReplaceTransaction(schema, spec, props, location);

if (!tables.exists(location)) { /* create instead of replace, or fail early */ }

try { Transaction tx = tables.replaceTransaction(schema, spec, props, location); } catch (NoSuchTableException e) { Transaction tx = tables.createTransaction(schema, spec, props, location); }

When it happens

Trigger: Calling replaceTransaction(location, ...) when no table metadata exists at the location. Common when the table was deleted, the location is wrong, or the table was never created.

Common situations: Typo in table location; table dropped by another job between check and replace; assuming replace implies create (it does not).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Table does not exist: %s
• Invalid table identifier: %s
• Failed to list tables under: %s
• Namespace delete failed: %s
• Cannot set namespace properties " + namespace + " : setPrope

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