Spring Boot in a container cannot connect to the MySQL container
Communications link failureShort answer
In Compose the app and MySQL are separate containers. The failure comes from three settings: a JDBC URL that still says localhost, the published host port used where the container port belongs, or an app that starts while MySQL is still preparing its first database. Fix the URL through an environment variable and add a health check.
Fix it fast
1Find out which cause you have
Read the JDBC URL the application actually uses, and the state of the MySQL container. The environment of the running app container shows what overrides application.properties.
docker compose exec app env | grep -i SPRING_DATASOURCE docker compose ps docker compose logs mysql --tail 202Match what you see, then jump to its fix
- 1
The URL in the log or in application.properties starts with jdbc:mysql://localhostThe JDBC URL still points at localhostFix - 2
mysql is mapped as 3307:3306 and the app URL ends in :3307The URL uses the port published on the hostFix - 3
The failure shows only on the first start or after docker compose down -v, and a restart of the app container makes it passThe app starts before MySQL has finished preparing its databaseFix
- 1
What does the error look like?
Communications link failure
Cause 1 of 3
The JDBC URL still points at localhost
1Check
In the app container, localhost is the app container itself. Other containers are reached by their Compose service name, which each service registers with an internal DNS server. Spring Boot lets an environment variable override a value from application.properties, and the variable for spring.datasource.url is SPRING_DATASOURCE_URL: dots become underscores and the name is upper case.
grep -n "datasource" src/main/resources/application.properties
docker compose exec app env | grep -i datasource2Fix
Set the URL, user and password for the container through the compose file, with the service name of MySQL as host.
services:
app:
build: .
environment:
SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/appdb
SPRING_DATASOURCE_USERNAME: appuser
SPRING_DATASOURCE_PASSWORD: change-me-example
mysql:
image: mysql:8.4
environment:
MYSQL_ROOT_PASSWORD: change-me-example
MYSQL_DATABASE: appdb
MYSQL_USER: appuser
MYSQL_PASSWORD: change-me-example3Verify
Recreate the app container and watch for the pool to start.
docker compose up -d --force-recreate app
docker compose logs app --tail 30Confirmed by docs.spring.io
Cause 2 of 3
The URL uses the port published on the host
1Check
In a ports entry the left number is for clients on the host, and the right number is the container port. Services talk to each other on the container port.
docker compose config | grep -n -E -B2 -A2 "published|ports"2Fix
Use the right-hand number in the URL inside the network, and keep the mapped port for tools on your laptop.
# inside Compose
SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/appdb
# from the host, with ports: ["3307:3306"]
jdbc:mysql://localhost:3307/appdb3Verify
The app logs no connection error after the next start.
docker compose logs app --tail 30Confirmed by docs.docker.com
Cause 3 of 3
The app starts before MySQL has finished preparing its database
1Check
On a fresh data directory the image creates the database first, and the server does not take connections until that is done. Compose waits only until the container runs, not until the server is ready, so the app's first attempt arrives too early.
docker compose logs mysql --tail 402Fix
Give MySQL a health check and make the app wait for it. mysqladmin ping reports success when the server is running, even if it then refuses the login.
services:
mysql:
image: mysql:8.4
# MYSQL_ROOT_PASSWORD is set in the environment of this service
healthcheck:
test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p$${MYSQL_ROOT_PASSWORD}"]
interval: 10s
retries: 5
start_period: 30s
timeout: 10s
app:
depends_on:
mysql:
condition: service_healthy3Verify
docker compose ps shows mysql as healthy, then the app container starts.
docker compose up -d && docker compose psConfirmed by docs.docker.com
How do I stop it coming back?
- Keep the datasource settings of containers in the compose file, and leave application.properties for the values that do not change between environments.
- Run the app with a spring profile for Docker, so a local profile with localhost cannot end up in the image.
- Give every database service a health check and depend on it with service_healthy.
- Print the final URL at start-up (without the password) so a wrong host is visible in the first log lines.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Databases
JDBC cannot talk to MySQL: Communications link failure
The last packet sent successfully to the server was 0 milliseconds ago.
Communications link failure means the TCP link to MySQL could not be opened or was closed.
3 causes, each with a fixDatabases
MySQL Connector/J: EOFException, expected to read 4 bytes, read 0 bytes
Communications link failure
The MySQL server or something between you and it closed the connection, and the driver found out only when it tried to use it.
3 causes, each with a fixDatabases
The MariaDB or MySQL container ignores the root password you set
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
The official MariaDB and MySQL images apply their password variables only while initialising an empty data directory.
3 causes, each with a fixDatabases
Hibernate fails on a CREATE or ALTER TABLE statement at startup
Error executing DDL "alter table events drop foreign key FKg0mkvgsqn8584qoql6a2rxheq" via JDBC Statement
Hibernate generated a CREATE, ALTER or DROP statement and MySQL refused it.
3 causes, each with a fixDatabases
Hibernate cannot resolve org.hibernate.dialect.MySQL5Dialect as a strategy
Unable to resolve name [org.hibernate.dialect.MySQL5Dialect] as strategy [org.hibernate.dialect.Dialect]
Hibernate 6 stopped using version-specific dialects such as MySQL5Dialect.
3 causes, each with a fixDatabases
Spring Boot fails on startup: HikariPool-1 exception during pool initialization
Caused by: ... (the underlying driver exception)
HikariCP opens one connection when the pool starts, and the startup fails when that connection fails.
3 causes, each with a fix