apache/beam · error · SqlUtil.newContextException

Database ' ' already exists.

Error message

Database '%s' already exists.

What it means

Thrown by CatalogSchema.createDatabase when the database already exists in the catalog and the statement did not include IF NOT EXISTS and the name is not the default database. Calcite wraps it with the statement's parser position.

Solutions

1. Add IF NOT EXISTS to the CREATE DATABASE statement.
2. Drop the existing database first if recreation is intended (DROP DATABASE ... ).
3. Use the built-in 'default' database instead of creating a duplicate.
4. Guard the script to only create the database when absent.

Example fix

// before
CREATE DATABASE analytics;
// after
CREATE DATABASE IF NOT EXISTS analytics;

// Java: skip DDL if the database already exists
if (!catalog.databaseExists(name)) {
  stmt.execute("CREATE DATABASE " + name);
}

// Java
catch (SQLException e) {
  if (e.getMessage().matches("(?s).*Database '.*' already exists\\.")) {
    LOG.info("database already present; continuing");
  } else throw e;
}

When it happens

Trigger: Executing `CREATE DATABASE name` (without IF NOT EXISTS) when subSchemas/catalog already contains `name`, and name != DEFAULT.

Common situations: Re-running an idempotent setup/seed SQL script, a migration script executed twice, or CI re-applying DDL against a persistent catalog.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• Attempting to create database
• Attempting to drop database
• Cannot use database: ' ' not found.
• Database ' ' does not exist.
• Encountered an error when creating database

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

Appendix: source

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

        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)));
  }

  public void useDatabase(SqlIdentifier identifier) {
    String name = SqlDdlNodes.name(identifier);
    if (!subSchemas.containsKey(name)) {
      if (!catalog.databaseExists(name)) {
        throw SqlUtil.newContextException(
            identifier.getParserPosition(),
            RESOURCE.internal(String.format("Cannot use database: '%s' not found.", name)));
      }
      subSchemas.put(name, new BeamCalciteSchema(name, connection, catalog.metaStore(name)));
    }

View on GitHub (pinned to 12126d8942)