apache/iceberg · error · IllegalArgumentException

Illegal table name:

Error message

Illegal table name:

What it means

FlinkCatalog.toIdentifier converts a Flink ObjectPath/TablePath into an Iceberg TableIdentifier. When the table name has more parts than the catalog's namespace depth can absorb (e.g. a 3-level name under a 1-level base namespace, and it is not a metadata table), it throws IllegalArgumentException("Illegal table name:").

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java:166

    String[] namespace = new String[baseNamespace.levels().length + 1];
    System.arraycopy(baseNamespace.levels(), 0, namespace, 0, baseNamespace.levels().length);
    namespace[baseNamespace.levels().length] = newLevel;
    return Namespace.of(namespace);
  }

  TableIdentifier toIdentifier(ObjectPath path) {
    String objectName = path.getObjectName();
    List<String> tableName = Splitter.on('$').splitToList(objectName);

    if (tableName.size() == 1) {
      return TableIdentifier.of(
          appendLevel(baseNamespace, path.getDatabaseName()), path.getObjectName());
    } else if (tableName.size() == 2 && MetadataTableType.from(tableName.get(1)) != null) {
      return TableIdentifier.of(
          appendLevel(appendLevel(baseNamespace, path.getDatabaseName()), tableName.get(0)),
          tableName.get(1));
    } else {
      throw new IllegalArgumentException("Illegal table name:" + objectName);
    }
  }

  @Override
  public List<String> listDatabases() throws CatalogException {
    if (asNamespaceCatalog == null) {
      return Collections.singletonList(getDefaultDatabase());
    }

    return asNamespaceCatalog.listNamespaces(baseNamespace).stream()
        .map(n -> n.level(n.levels().length - 1))
        .collect(Collectors.toList());
  }

  @Override
  public CatalogDatabase getDatabase(String databaseName)
      throws DatabaseNotExistException, CatalogException {
    if (asNamespaceCatalog == null) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Reference the table with the correct number of levels for the catalog: use flinkCatalog name + database + table only, e.g. SELECT * FROM iceberg_db.`table` instead of iceberg_db.`ns.table.sub`.
2. Set the catalog's base-namespace property so the extra level maps onto a real Iceberg namespace (base-namespace = ns makes a.b.table valid).
3. Verify whether the second element is a valid metadata table type; only 2-level names ending in a metadata table keyword are accepted.
4. Query which databases exist via SHOW DATABASES to see the supported namespace layout.

Example fix

// before: 3-level reference under flat catalog
TableIdentifier id = flinkCatalog.toIdentifier(new ObjectPath(new ObjectPath("db"), "a.b.table"));
// after: configure base-namespace or use 2-level path
TableIdentifier id = flinkCatalog.toIdentifier(new ObjectPath(new ObjectPath("db"), "a.table"));

String[] parts = objectName.split("\\.");
if (parts.length > 2) throw new IllegalArgumentException("Too many levels for Flink Iceberg catalog: " + objectName);

try {
  Table table = flinkCatalog.getTable(objectPath);
} catch (IllegalArgumentException e) {
  // fix identifier levels or base-namespace config
}

When it happens

Trigger: Calling table/tableExists/dropTable/renameTable or creating a table loader with an ObjectPath whose name contains extra dot-separated levels (size 3+ not a metadata table) or other shapes that don't fit baseNamespace + database + object.

Common situations: Flink catalogs configured with a base namespace where users reference nested Iceberg namespaces (a.b.table) in SQL; using Flink metadata-table syntax with a name that resolves to too many levels; copy-pasted fully qualified names from other engines.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Illegal table name:
• Namespaces are not supported by catalog:
• Database properties should not contain key: 'comment'.
• Can not alter the default database when the iceberg catalog
• Source table %s contains one/all of the reserved property ke

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