The MySQL container stops with: the designated data directory is unusable
The designated data directory /var/lib/mysql/ is unusable. You can remove all files that the server added to it.Short answer
This message closes a failed first start. The line just above it in the log tells you why: the data directory was not empty, because an earlier attempt left files in it, or the mysql user could not write to the mounted folder. Empty the folder or use a fresh volume, and fix the owner.
Fix it fast
1Find out which cause you have
Read the lines that come before the 'unusable' message. They hold the real reason and decide which cause applies.
docker compose logs db | head -n 302Match what you see, then jump to its fix
- 1
A line about the data directory existing or having files, right before the 'unusable' line.The data directory already has files in itFix - 2
A permission or not-writable line in the log, right before the 'unusable' line.The mounted folder is not writable for the mysql userFix - 3
The compose file sets user: or --user, and the log shows permission errors on /var/lib/mysql.The image was started with a user that is not allowed to own the dataFix
- 1
What does the error look like?
The designated data directory /var/lib/mysql/ is unusable. You can remove all files that the server added to it.[ERROR] --initialize specified but the data directory exists. Aborting.
Cause 1 of 3
The data directory already has files in it
1Check
mysqld --initialize aborts when the directory contains anything except entries whose names start with a period. A failed earlier start, files copied in by hand all count.
ls -la ./mysql-data2Fix
If the contents are disposable, empty the folder (or remove the named volume) so initialisation starts clean.
docker compose down
sudo rm -rf ./mysql-data/* ./mysql-data/.[!.]* # only when the data is disposable
docker compose up -d3Verify
The log shows the server starting instead of the abort message.
docker compose logs db | tail -n 10Confirmed by dev.mysql.com
Cause 2 of 3
The mounted folder is not writable for the mysql user
1Check
Database files must be owned by the mysql account so the server can read and write them. With a bind mount the image does not set that for you, so the owner of the host folder decides.
ls -ldn ./mysql-data
docker run --rm mysql:8.4 id mysql2Fix
Give the folder to the numeric id of the mysql user inside the image. Alternatively switch to a named volume that Docker manages.
docker compose down
sudo chown -R "$(docker run --rm mysql:8.4 id -u mysql)":"$(docker run --rm mysql:8.4 id -g mysql)" ./mysql-data
docker compose up -d3Verify
The container reaches the ready-for-connections line.
docker compose logs db | grep -i 'ready for connections'Confirmed by dev.mysql.com
Cause 3 of 3
The image was started with a user that is not allowed to own the data
1Check
The image can run as any user other than root (id 0), but the data folder must be set up for that user.
grep -n -E 'user:|--user' compose.yaml2Fix
Either remove the user setting, or make sure the data folder is owned by exactly that user id.
# compose.yaml (example)
services:
db:
image: mysql:8.4
user: "1000:1000"
volumes:
- ./mysql-data:/var/lib/mysql
# host
sudo chown -R 1000:1000 ./mysql-data3Verify
Recreate the container and read the log.
docker compose up -d && docker compose logs db | tail -n 10Confirmed by hub.docker.com
How do I stop it coming back?
- Use a named volume for /var/lib/mysql unless you need the files on the host.
- Read the first error in the log, not the last; the last line is usually a summary.
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.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Databases
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
PHP throws "could not find driver" when it opens a PDO connection
Fatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12
PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded.
4 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fix