Jira startup fails with database "Unsupported character encoding"
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
When starting up Jira, you encounter the following warning.
Reviewing the atlassian-jira.log we can see that the startup fails due to the character encoding 'UTF8mb4' being rejected by the database server.
The same instructions also apply if you have a different character encoding listed here.
2024-03-15 07:54:10,697-0300 JIRA-Bootstrap ERROR [c.a.config.bootstrap.DefaultAtlassianBootstrapManager] Could not successfully test your database:
java.sql.SQLException: Unsupported character encoding 'UTF8mb4'
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:129)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:97)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:89)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:63)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:73)
at com.mysql.cj.jdbc.exceptions.SQLExceptionsMapping.translateException(SQLExceptionsMapping.java:85)
at com.mysql.cj.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:444)
at com.mysql.cj.jdbc.ConnectionImpl.getInstance(ConnectionImpl.java:241)
at com.mysql.cj.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:198)
...
Caused by: com.mysql.cj.exceptions.WrongArgumentException: Unsupported character encoding 'UTF8mb4'
...
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:61)
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:105)
at com.mysql.cj.util.StringUtils.getBytes(StringUtils.java:231)
at com.mysql.cj.jdbc.JdbcPropertySetImpl.postInitialization(JdbcPropertySetImpl.java:66)
at com.mysql.cj.conf.DefaultPropertySet.initializeProperties(DefaultPropertySet.java:231)
at com.mysql.cj.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:390)
... 34 more
Caused by: java.io.UnsupportedEncodingException: UTF8mb4
at java.base/java.lang.StringCoding.encode(StringCoding.java:440)
at java.base/java.lang.String.getBytes(String.java:941)
at com.mysql.cj.util.StringUtils.getBytes(StringUtils.java:229)
... 37 more
2024-03-15 07:54:10,699-0300 JIRA-Bootstrap ERROR [c.a.jira.health.MySQLHealthCheckTemplate] There is database configuration error!
com.atlassian.config.bootstrap.BootstrapException: java.sql.SQLException: Unsupported character encoding 'UTF8mb4'
at com.atlassian.config.bootstrap.DefaultAtlassianBootstrapManager.getTestDatabaseConnection(DefaultAtlassianBootstrapManager.java:294)
at com.atlassian.jira.config.database.JdbcDatasource.getConnection(JdbcDatasource.java:228)
at com.atlassian.jira.health.MySQLHealthCheckTemplate.verify(MySQLHealthCheckTemplate.java:70)
...
Caused by: java.sql.SQLException: Unsupported character encoding 'UTF8mb4'
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:129)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:97)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:89)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:63)
at com.mysql.cj.jdbc.exceptions.SQLError.createSQLException(SQLError.java:73)
at com.mysql.cj.jdbc.exceptions.SQLExceptionsMapping.translateException(SQLExceptionsMapping.java:85)
at com.mysql.cj.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:444)
at com.mysql.cj.jdbc.ConnectionImpl.getInstance(ConnectionImpl.java:241)
at com.mysql.cj.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:198)
at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:677)
at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:228)
at com.atlassian.config.bootstrap.DefaultAtlassianBootstrapManager.getTestDatabaseConnection(DefaultAtlassianBootstrapManager.java:285)
... 29 more
Caused by: com.mysql.cj.exceptions.WrongArgumentException: Unsupported character encoding 'UTF8mb4'
...
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:61)
at com.mysql.cj.exceptions.ExceptionFactory.createException(ExceptionFactory.java:105)
at com.mysql.cj.util.StringUtils.getBytes(StringUtils.java:231)
at com.mysql.cj.jdbc.JdbcPropertySetImpl.postInitialization(JdbcPropertySetImpl.java:66)
at com.mysql.cj.conf.DefaultPropertySet.initializeProperties(DefaultPropertySet.java:231)
at com.mysql.cj.jdbc.ConnectionImpl.<init>(ConnectionImpl.java:390)
... 34 more
Caused by: java.io.UnsupportedEncodingException: UTF8mb4
at java.base/java.lang.StringCoding.encode(StringCoding.java:440)
at java.base/java.lang.String.getBytes(String.java:941)
at com.mysql.cj.util.StringUtils.getBytes(StringUtils.java:229)
... 37 more
...
2024-03-15 07:54:10,718-0300 JIRA-Bootstrap ERROR [c.a.jira.health.HealthChecks] JIRA couldn't connect to your database
2024-03-15 07:54:10,718-0300 JIRA-Bootstrap ERROR [c.a.jira.health.HealthChecks] JIRA failed to establish a connection to your database.
This could be because:
- Your database isn't running
- The configuration of your dbconfig.xml file is incorrect (user, password, or database URL etc.)
- There is a network issue between JIRA and your database (e.g. firewall, database doesn't allow remote access etc.)
There are several other solutions you can try, review our documentation and see what works for you.Environment
- On-Premisses Jira & MySQL database.
Diagnosis
Reviewing the '<Jira_home>/dbconfig.xml' file, we can see that the 'characterEncoding' parameter has been set with the 'UTF8mb4' value.
...
<url>jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/jiratest?useUnicode=true&characterEncoding=UTF8mb4&sessionVariables=default_storage_engine=InnoDB</url>
...Cause
This problem is usually caused by a slight mixup of concepts as the Connecting Jira to MySQL 8.0 documentation indicates that 'utf8mb4' should be used as the character set when setting up a MySQL database. While 'UTF8mb4' should be the character set, 'UTF8' should be the character encoding.
We can think of it as:
- Character Set is the type of characters you can use.
- Character Encoding is the way these characters are stored.
References:
Solution
To resolve this issue, we'll need to adjust the connection string on the 'dbconfig.xml' file.
To do so, we have two options:
Change the 'characterEncoding' value from 'UTF8mb4' to 'UTF8'.
<url>jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/jiratest?useUnicode=true&characterEncoding=UTF8&sessionVariables=default_storage_engine=InnoDB</url>Remove the encoding parameters from the string, leaving only the 'sessionVariables' section.
<url>jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/jiratest?sessionVariables=default_storage_engine=InnoDB</url>