apache/druid · critical · IllegalStateException

Druid requires its MySQL database to be created with an UTF8

Error message

Druid requires its MySQL database to be created with an UTF8 charset, found `%1$s`. The recommended charset is `utf8mb4`.

What it means

MySQLConnector.tableExists() runs 'SELECT @@character_set_database' during initialization and throws if the database charset does not start with 'utf8'. Druid metadata storage requires a UTF-8 charset (utf8mb4 recommended) to store its tables correctly.

Source

Thrown at extensions-core/mysql-metadata-storage/src/main/java/org/apache/druid/metadata/storage/mysql/MySQLConnector.java:221

  }

  @Override
  protected String getDropIndexStatement(String indexName, String tableName)
  {
    // MySQL requires the target table in a DROP INDEX statement.
    return StringUtils.format("DROP INDEX %s ON %s", indexName, tableName);
  }

  @Override
  public boolean tableExists(Handle handle, String tableName)
  {
    String databaseCharset = handle
        .createQuery("SELECT @@character_set_database")
        .map(StringMapper.FIRST)
        .first();

    if (!databaseCharset.startsWith("utf8")) {
      throw new ISE(
          "Druid requires its MySQL database to be created with an UTF8 charset, found `%1$s`. "
          + "The recommended charset is `utf8mb4`.",
          databaseCharset
      );
    } else if (!"utf8mb4".equals(databaseCharset)) {
      log.warn("The current database charset `%1$s` does not match the recommended charset `utf8mb4`", databaseCharset);
    }

    return !handle.createQuery("SHOW tables LIKE :tableName")
                  .bind("tableName", tableName)
                  .list()
                  .isEmpty();
  }

  @Override
  protected boolean connectorIsTransientException(Throwable e)
  {
    if (myTransientExceptionClass != null) {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Convert the database: ALTER DATABASE druid CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
2. Recreate the metadata database with DEFAULT CHARSET=utf8mb4
3. Set the MySQL server/instance default character-set-server=utf8mb4 for new databases

Example fix

-- before
CREATE DATABASE druid;
-- after
CREATE DATABASE druid CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

final String cs = jdbcTemplate.queryForObject("SELECT @@character_set_database", String.class);
if (!cs.startsWith("utf8")) { throw new IllegalStateException("Druid DB must use utf8mb4, found " + cs); }

try { connector.init(); } catch (ISE e) { if (e.getMessage().contains("UTF8 charset")) { throw new DbSetupException("Recreate the database with utf8mb4: " + e.getMessage()); } throw e; }

When it happens

Trigger: Starting Druid against a MySQL database created with a non-UTF8 charset (e.g. latin1); the check runs on connector init when validating the metadata store.

Common situations: DBA provisioned the database with server-default charset latin1; older MySQL installs defaulting to latin1; database created before Druid deployment without explicit charset.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• SQLCatalogManager only works with SQL based metadata store a
• The gRPC query server requires either a Basic or Anonymous a
• Metric [%s] not whitelisted.
• Can't load TrustStore. Truststore path or password is not se
• druid.request.logging.transportUrl must be set when transpor

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/94d7dc3bd572ac67. Report an issue: GitHub.