{"record":{"id":"68ee7436c2913f99","repo":"apache/iceberg","slug":"database-s-already-exists-in-the-iceberg-catalog-68ee74","errorCode":null,"errorMessage":"Database %s already exists in the iceberg catalog %s.","messagePattern":"Database (.+?) already exists in the iceberg catalog (.+?)\\.","errorType":"exception","errorClass":"org.apache.flink.table.api.AlreadyExistsException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/FlinkDynamicTableFactory.java","lineNumber":213,"sourceCode":"\n    String catalogDatabase = flinkConf.get(FlinkCreateTableOptions.CATALOG_DATABASE, databaseName);\n    Preconditions.checkArgument(\n        catalogDatabase != null,\n        \"Invalid database name: null. Set %s create table option or specify fully qualified table name.\",\n        FlinkCreateTableOptions.CATALOG_DATABASE);\n\n    String catalogTable = flinkConf.get(FlinkCreateTableOptions.CATALOG_TABLE, tableName);\n\n    FlinkCatalog flinkCatalog = createCatalogLoader(mergedProps, catalogName);\n    ObjectPath objectPath = new ObjectPath(catalogDatabase, catalogTable);\n\n    // Create database if not exists in the external catalog.\n    if (!flinkCatalog.databaseExists(catalogDatabase)) {\n      try {\n        flinkCatalog.createDatabase(\n            catalogDatabase, new CatalogDatabaseImpl(Maps.newHashMap(), null), true);\n      } catch (DatabaseAlreadyExistException e) {\n        throw new AlreadyExistsException(\n            e,\n            \"Database %s already exists in the iceberg catalog %s.\",\n            catalogName,\n            catalogDatabase);\n      }\n    }\n\n    // Create table if not exists in the external catalog.\n    if (!flinkCatalog.tableExists(objectPath)) {\n      try {\n        flinkCatalog.createIcebergTable(objectPath, resolvedCatalogTable, true);\n      } catch (TableAlreadyExistException e) {\n        throw new AlreadyExistsException(\n            e,\n            \"Table %s already exists in the database %s and catalog %s\",\n            catalogTable,\n            catalogDatabase,\n            catalogName);","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/FlinkDynamicTableFactory.java#L195-L231","documentation":"When FlinkDynamicTableFactory creates a table loader and the target Iceberg database does not exist, it tries to create it with ignoreIfExists=false semantics via createDatabase; if the database was created concurrently (DatabaseAlreadyExistException), it rethrows as AlreadyExistsException. It signals a race or an existing database the existence pre-check missed.","triggerScenarios":"createTableLoader (invoked from createDynamicTableSource/createDynamicTableSink) when databaseExists(catalogDatabase) returned false but flinkCatalog.createDatabase then throws DatabaseAlreadyExistException — typically a concurrent job creating the same database.","commonSituations":"Multiple Flink jobs/queries starting simultaneously against a fresh Iceberg catalog and racing to create the same database; stale metadata in the factory's cached catalog view.","solutions":["Treat as benign if the database already exists — retry the query; the database is now present.","Pre-create the database before submitting jobs (e.g. CREATE DATABASE IF NOT EXISTS in Flink SQL or via the Iceberg catalog API).","Serialize job startup so concurrent writers don't race on database creation."],"exampleFix":"// before (SQL, racing jobs)\nCREATE TABLE iceberg_db.my_table ...; // each job auto-creates iceberg_db\n// after\nCREATE DATABASE IF NOT EXISTS iceberg_db;\nCREATE TABLE iceberg_db.my_table ...;","handlingStrategy":"try-catch","validationCode":"if (!flinkCatalog.databaseExists(dbName)) { /* pre-create once at deployment time */ }","typeGuard":null,"tryCatchPattern":"try {\n  flinkCatalog.createDatabase(db, new CatalogDatabaseImpl(Maps.newHashMap(), null), true);\n} catch (DatabaseAlreadyExistException e) {\n  // benign: another worker created it; proceed\n}","preventionTips":["Pre-create databases in deployment scripts before starting jobs.","Use ignoreIfExists=true when creating databases programmatically.","Avoid multiple concurrent jobs auto-creating the same fresh database."],"tags":["flink","catalog","database","already-exists","race-condition"],"backgroundTag":"file-already-exists","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"}