{"record":{"id":"94d7dc3bd572ac67","repo":"apache/druid","slug":"druid-requires-its-mysql-database-to-be-created-wi","errorCode":null,"errorMessage":"Druid requires its MySQL database to be created with an UTF8 charset, found `%1$s`. The recommended charset is `utf8mb4`.","messagePattern":"Druid requires its MySQL database to be created with an UTF8 charset, found `%1\\$s`\\. The recommended charset is `utf8mb4`\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"extensions-core/mysql-metadata-storage/src/main/java/org/apache/druid/metadata/storage/mysql/MySQLConnector.java","lineNumber":221,"sourceCode":"  }\n\n  @Override\n  protected String getDropIndexStatement(String indexName, String tableName)\n  {\n    // MySQL requires the target table in a DROP INDEX statement.\n    return StringUtils.format(\"DROP INDEX %s ON %s\", indexName, tableName);\n  }\n\n  @Override\n  public boolean tableExists(Handle handle, String tableName)\n  {\n    String databaseCharset = handle\n        .createQuery(\"SELECT @@character_set_database\")\n        .map(StringMapper.FIRST)\n        .first();\n\n    if (!databaseCharset.startsWith(\"utf8\")) {\n      throw new ISE(\n          \"Druid requires its MySQL database to be created with an UTF8 charset, found `%1$s`. \"\n          + \"The recommended charset is `utf8mb4`.\",\n          databaseCharset\n      );\n    } else if (!\"utf8mb4\".equals(databaseCharset)) {\n      log.warn(\"The current database charset `%1$s` does not match the recommended charset `utf8mb4`\", databaseCharset);\n    }\n\n    return !handle.createQuery(\"SHOW tables LIKE :tableName\")\n                  .bind(\"tableName\", tableName)\n                  .list()\n                  .isEmpty();\n  }\n\n  @Override\n  protected boolean connectorIsTransientException(Throwable e)\n  {\n    if (myTransientExceptionClass != null) {","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/mysql-metadata-storage/src/main/java/org/apache/druid/metadata/storage/mysql/MySQLConnector.java#L203-L239","documentation":"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.","triggerScenarios":"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.","commonSituations":"DBA provisioned the database with server-default charset latin1; older MySQL installs defaulting to latin1; database created before Druid deployment without explicit charset.","solutions":["Convert the database: ALTER DATABASE druid CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;","Recreate the metadata database with DEFAULT CHARSET=utf8mb4","Set the MySQL server/instance default character-set-server=utf8mb4 for new databases"],"exampleFix":"-- before\nCREATE DATABASE druid;\n-- after\nCREATE DATABASE druid CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;","handlingStrategy":"validation","validationCode":"final String cs = jdbcTemplate.queryForObject(\"SELECT @@character_set_database\", String.class);\nif (!cs.startsWith(\"utf8\")) { throw new IllegalStateException(\"Druid DB must use utf8mb4, found \" + cs); }","typeGuard":null,"tryCatchPattern":"try { connector.init(); } catch (ISE e) { if (e.getMessage().contains(\"UTF8 charset\")) { throw new DbSetupException(\"Recreate the database with utf8mb4: \" + e.getMessage()); } throw e; }","preventionTips":["Always create the metadata DB with DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci","Add a pre-deployment DB charset check to your provisioning scripts","Set character-set-server=utf8mb4 in the MySQL server config"],"tags":["mysql","charset","metadata-store","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}