apache/beam · error · SqlUtil.newContextException

Encountered an error when creating database

Error message

Encountered an error when creating database '%s': %s

What it means

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.

Solutions

1. Inspect the wrapped cause ('%s' second argument) for the real backend error and fix it (connectivity, permissions, name validity).
2. Verify the catalog's metaStore configuration before running DDL.
3. Check the database name for characters the catalog rejects and quote/adjust it.
4. If the database already exists (some backends throw), use `CREATE DATABASE IF NOT EXISTS`.

Example fix

// before
CREATE DATABASE mydb;
// after
CREATE DATABASE IF NOT EXISTS mydb; -- and fix the underlying cause reported in the message

// Java: check the database isn't already creatable/valid before DDL
boolean exists = catalog.databaseExists(name);
boolean nameValid = name != null && name.matches("[A-Za-z_][A-Za-z0-9_]*");
if (!nameValid) throw new IllegalArgumentException("invalid db name: " + name);

// Java
try {
  statement.execute("CREATE DATABASE " + name);
} catch (SQLException e) {
  if (e.getMessage().contains("Encountered an error when creating database")) {
    // inspect cause embedded in message; fall back to IF NOT EXISTS
    statement.execute("CREATE DATABASE IF NOT EXISTS " + name);
  } else throw e;
}

When it happens

Trigger: Executing `CREATE DATABASE name` where catalog.createDatabase(name) raises an exception (backend/metaStore failure, invalid name, IO error, or unsupported catalog operation).

Common situations: 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.

Related errors

• Encountered an error when dropping database
• Attempting to create database
• Attempting to drop database
• Cannot use database: ' ' not found.
• Database ' ' already exists.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/f12ebaa26ec56b32. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/CatalogSchema.java:102

    }
    return checkStateNotNull(
        beamCalciteSchema, "Could not find BeamCalciteSchema for table: '%s'", tablePath);
  }

  public void createDatabase(SqlIdentifier databaseIdentifier, boolean ifNotExists) {
    String name = SqlDdlNodes.name(databaseIdentifier);
    boolean alreadyExists = subSchemas.containsKey(name);

    if (!alreadyExists || name.equals(DEFAULT)) {
      try {
        LOG.info("Creating database '{}'", name);
        if (catalog.createDatabase(name)) {
          LOG.info("Successfully created database '{}'", name);
        } else {
          alreadyExists = true;
        }
      } catch (Exception e) {
        throw SqlUtil.newContextException(
            databaseIdentifier.getParserPosition(),
            RESOURCE.internal(
                format("Encountered an error when creating database '%s': %s", name, e)));
      }
    }

    if (alreadyExists) {
      String message = format("Database '%s' already exists.", name);
      if (ifNotExists || name.equals(DEFAULT)) {
        LOG.info("Database '{}' already exists.", name);
      } else {
        throw SqlUtil.newContextException(
            databaseIdentifier.getParserPosition(), RESOURCE.internal(message));
      }
    }

    subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));
  }

View on GitHub (pinned to 12126d8942)