Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

MySQL: could not create connection to database server

ErrorMySQLNonTransientConnectionException: Could not create connection to database server

Short answer

These messages are wrappers. The real reason is in the last 'Caused by' line of the stack trace. In practice it is one of three things: the MySQL server is not reachable on that host and port, the server rejects the user or host, or the app starts before the database is ready. Read the last cause, then match it below.

  • Applies to MySQL 8.4, MySQL Connector/J 9, Java 21, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the deepest cause in the stack trace and test the same host, port and user outside Java with the mysql client. If the client fails too, the problem is the server or the account, not your code.

    grep -n 'Caused by' app.log | tail -n 3
    mysql -h 127.0.0.1 -P 3306 -u app_user -p
  2. 2Match what you see, then jump to its fix

    1. 1The last cause names a refused connection or a communications failure, and the mysql client also cannot connectThe server is not running or not reachable on that host and portFix
    2. 2The last cause says Access denied, or that the host is not allowed to connectThe server refuses this user, password or client hostFix
    3. 3Works on a second start; the failure is only at boot, usually with Docker ComposeThe app starts before the database is readyFix

What does the error look like?

  • MySQLNonTransientConnectionException: Could not create connection to database server
  • Could not create connection to database server. Attempted reconnect 3 times. Giving up.
  • Cannot create PoolableConnectionFactory

Cause 1 of 3

The server is not running or not reachable on that host and port

1Check

MySQL's own guide lists the usual reasons: mysqld is not running, skip_networking blocks TCP/IP, bind_address=127.0.0.1 accepts only local connections, or a firewall blocks port 3306. Connector/J needs TCP/IP.

ps xa | grep mysqld
mysqladmin -h 127.0.0.1 --port=3306 version

2Fix

Start the server, and for a remote database make it listen on a reachable address and open the port to the app host. Then put the same host and port in the JDBC URL.

# application.properties
spring.datasource.url=jdbc:mysql://db.example.com:3306/appdb

3Verify

The mysqladmin command prints version information, and the app starts.

mysqladmin -h db.example.com --port=3306 version

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 3

The server refuses this user, password or client host

1Check

MySQL matches both the user name and the client host. A password typed with a wrong value, an old password in an option file, or an account that exists only for localhost all fail. A mysql client that works while the Java program fails points at the program's own settings.

mysql --no-defaults -h db.example.com -u app_user -p appdb
mysql -u root -p -e "SELECT user, host FROM mysql.user WHERE user='app_user';"

2Fix

Create or correct the account for the host the app connects from, and give it rights on the database. Copy the exact user name and password into the application settings.

CREATE USER 'app_user'@'10.0.0.%' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON appdb.* TO 'app_user'@'10.0.0.%';

3Verify

Log in from the app host with the mysql client, then start the app.

mysql -h db.example.com -u app_user -p appdb -e 'SELECT 1'

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 3

The app starts before the database is ready

1Check

Compose depends_on alone waits only until the database container is running, not until it accepts connections. A connection pool that creates connections at start (DBCP's initialSize) fails the whole app start when the database is not ready yet.

docker compose ps

2Fix

Add a healthcheck to the database service and make the app wait for it with condition: service_healthy.

services:
  app:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mysql:8.4
    healthcheck:
      test: ["CMD-SHELL", "<your database readiness command>"]
      interval: 10s
      retries: 5
      start_period: 30s

3Verify

Bring the stack up from scratch and check that the app container stays up.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Log the full cause chain at startup so the root cause is never hidden behind the wrapper.
  • Keep the database host, port, user and password in one place and test them with the mysql client before a deploy.
  • Give every database container a healthcheck and make dependants wait for it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.