{"record":{"id":"f12ebaa26ec56b32","repo":"apache/beam","slug":"encountered-an-error-when-creating-database-s-s","errorCode":null,"errorMessage":"Encountered an error when creating database '%s': %s","messagePattern":"Encountered an error when creating database '(.+?)': (.+?)","errorType":"exception","errorClass":"SqlUtil.newContextException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java","lineNumber":102,"sourceCode":"    }\n    return checkStateNotNull(\n        beamCalciteSchema, \"Could not find BeamCalciteSchema for table: '%s'\", tablePath);\n  }\n\n  public void createDatabase(SqlIdentifier databaseIdentifier, boolean ifNotExists) {\n    String name = SqlDdlNodes.name(databaseIdentifier);\n    boolean alreadyExists = subSchemas.containsKey(name);\n\n    if (!alreadyExists || name.equals(DEFAULT)) {\n      try {\n        LOG.info(\"Creating database '{}'\", name);\n        if (catalog.createDatabase(name)) {\n          LOG.info(\"Successfully created database '{}'\", name);\n        } else {\n          alreadyExists = true;\n        }\n      } catch (Exception e) {\n        throw SqlUtil.newContextException(\n            databaseIdentifier.getParserPosition(),\n            RESOURCE.internal(\n                format(\"Encountered an error when creating database '%s': %s\", name, e)));\n      }\n    }\n\n    if (alreadyExists) {\n      String message = format(\"Database '%s' already exists.\", name);\n      if (ifNotExists || name.equals(DEFAULT)) {\n        LOG.info(\"Database '{}' already exists.\", name);\n      } else {\n        throw SqlUtil.newContextException(\n            databaseIdentifier.getParserPosition(), RESOURCE.internal(message));\n      }\n    }\n\n    subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));\n  }","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java#L84-L120","documentation":"Thrown by CatalogSchema.createDatabase when the underlying catalog's createDatabase(name) call throws. Beam SQL wraps the original exception into a Calcite context exception at the DDL statement's parser position. It means the CREATE DATABASE DDL failed inside the catalog backend, not in the SQL parser itself.","triggerScenarios":"Executing `CREATE DATABASE name` where catalog.createDatabase(name) raises an exception (backend/metaStore failure, invalid name, IO error, or unsupported catalog operation).","commonSituations":"Misconfigured catalog/metaStore (e.g. Hive metaStore unreachable), backend rejecting a database name with illegal characters, permission failures on the underlying store, or a catalog implementation bug surfaced through DDL.","solutions":["Inspect the wrapped cause ('%s' second argument) for the real backend error and fix it (connectivity, permissions, name validity).","Verify the catalog's metaStore configuration before running DDL.","Check the database name for characters the catalog rejects and quote/adjust it.","If the database already exists (some backends throw), use `CREATE DATABASE IF NOT EXISTS`."],"exampleFix":"// before\nCREATE DATABASE mydb;\n// after\nCREATE DATABASE IF NOT EXISTS mydb; -- and fix the underlying cause reported in the message","handlingStrategy":"try-catch","validationCode":"// Java: check the database isn't already creatable/valid before DDL\nboolean exists = catalog.databaseExists(name);\nboolean nameValid = name != null && name.matches(\"[A-Za-z_][A-Za-z0-9_]*\");\nif (!nameValid) throw new IllegalArgumentException(\"invalid db name: \" + name);","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n  statement.execute(\"CREATE DATABASE \" + name);\n} catch (SQLException e) {\n  if (e.getMessage().contains(\"Encountered an error when creating database\")) {\n    // inspect cause embedded in message; fall back to IF NOT EXISTS\n    statement.execute(\"CREATE DATABASE IF NOT EXISTS \" + name);\n  } else throw e;\n}","preventionTips":["Validate database names against the catalog's rules before DDL.","Ensure the metaStore backend is reachable before running DDL scripts.","Prefer IF NOT EXISTS for idempotent scripts.","Log the wrapped cause to diagnose backend failures quickly."],"tags":["sql","ddl","database","apache-beam"],"backgroundTag":"database-write-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}