{"record":{"id":"c7c5dd7e4091627d","repo":"apache/iceberg","slug":"illegal-table-name-c7c5dd","errorCode":null,"errorMessage":"Illegal table name:","messagePattern":"Illegal table name:","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java","lineNumber":166,"sourceCode":"    String[] namespace = new String[baseNamespace.levels().length + 1];\n    System.arraycopy(baseNamespace.levels(), 0, namespace, 0, baseNamespace.levels().length);\n    namespace[baseNamespace.levels().length] = newLevel;\n    return Namespace.of(namespace);\n  }\n\n  TableIdentifier toIdentifier(ObjectPath path) {\n    String objectName = path.getObjectName();\n    List<String> tableName = Splitter.on('$').splitToList(objectName);\n\n    if (tableName.size() == 1) {\n      return TableIdentifier.of(\n          appendLevel(baseNamespace, path.getDatabaseName()), path.getObjectName());\n    } else if (tableName.size() == 2 && MetadataTableType.from(tableName.get(1)) != null) {\n      return TableIdentifier.of(\n          appendLevel(appendLevel(baseNamespace, path.getDatabaseName()), tableName.get(0)),\n          tableName.get(1));\n    } else {\n      throw new IllegalArgumentException(\"Illegal table name:\" + objectName);\n    }\n  }\n\n  @Override\n  public List<String> listDatabases() throws CatalogException {\n    if (asNamespaceCatalog == null) {\n      return Collections.singletonList(getDefaultDatabase());\n    }\n\n    return asNamespaceCatalog.listNamespaces(baseNamespace).stream()\n        .map(n -> n.level(n.levels().length - 1))\n        .collect(Collectors.toList());\n  }\n\n  @Override\n  public CatalogDatabase getDatabase(String databaseName)\n      throws DatabaseNotExistException, CatalogException {\n    if (asNamespaceCatalog == null) {","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/FlinkCatalog.java#L148-L184","documentation":"FlinkCatalog.toIdentifier converts a Flink ObjectPath into an Iceberg TableIdentifier relative to the catalog's base namespace. If the resulting name cannot be represented — e.g. the table name has more levels than expected or the metadata-table mapping fails — it throws IllegalArgumentException 'Illegal table name:'. It signals the requested name is not addressable through this catalog, not that the table is missing.","triggerScenarios":"Calling table/tableExists/dropTable/renameTable/createTableLoader with an ObjectPath whose name is neither a plain table nor a recognized 2-part metadata table form; nested or malformed identifiers (extra dots, wrong depth) passed from Flink SQL or the API.","commonSituations":"Referencing tables with unusual quoting in Flink SQL ('cat.db.db2.tbl' against a single-level catalog), typos in metadata-table suffixes, programmatic ObjectPath construction with the wrong arity.","solutions":["Use a two-part ObjectPath (database.object) matching the catalog's expected nesting; avoid extra levels.","If targeting an Iceberg metadata table, use an exact supported suffix (e.g. 'tbl.history', 'tbl.snapshots').","Print the full objectName being passed and correct the caller (SQL path, connector options) that built it.","For deep namespaces, configure the Flink catalog's base namespace so remaining depth is exactly 2."],"exampleFix":"// before\nObjectPath path = new ObjectPath(\"db\", \"a.b.c\"); // too many levels\n// after\nObjectPath path = new ObjectPath(\"db\", \"tbl\"); // database.table\n// or for metadata tables:\nObjectPath metaPath = new ObjectPath(\"db\", \"tbl.snapshots\");","handlingStrategy":"validation","validationCode":"// validate object path arity before calling catalog methods\nstatic void checkPath(ObjectPath path) {\n  String name = path.getObjectName();\n  boolean isMetadataTable = name != null && MetadataTableType.from(name) != null;\n  // plain table: objectName has no dot; metadata table: exactly one dot with valid suffix\n  if (name.contains(\".\") && !isMetadataTable) {\n    throw new IllegalArgumentException(\"unsupported table name: \" + name);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.dropTable(path);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Illegal table name\")) {\n    throw new ValidationException(\"cannot address \" + path + \" through this catalog: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Build ObjectPath with exactly database + table, never deeper nesting","Use exact Iceberg metadata-table suffixes (snapshots, history, files, ...) when targeting them","Check Flink SQL identifier quoting so 'db.tbl' is not parsed as extra levels"],"tags":["flink","catalog","identifier"],"backgroundTag":"invalid-identifier-format","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}