Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The MySQL container stops with: the designated data directory is unusable

ErrorThe 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.

  • Applies to mysql Docker image 8.4, Docker Engine 28, Docker Compose 2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 30
  2. 2Match what you see, then jump to its fix

    1. 1A line about the data directory existing or having files, right before the 'unusable' line.The data directory already has files in itFix
    2. 2A permission or not-writable line in the log, right before the 'unusable' line.The mounted folder is not writable for the mysql userFix
    3. 3The 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

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-data

2Fix

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 -d

3Verify

The log shows the server starting instead of the abort message.

docker compose logs db | tail -n 10

Confirmed by dev.mysql.com

Did this fix it?

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 mysql

2Fix

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 -d

3Verify

The container reaches the ready-for-connections line.

docker compose logs db | grep -i 'ready for connections'

Confirmed by dev.mysql.com

Did this fix it?

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.yaml

2Fix

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-data

3Verify

Recreate the container and read the log.

docker compose up -d && docker compose logs db | tail -n 10

Confirmed by hub.docker.com

Did this fix it?

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:

Related fixes

Databases

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 fix

Next step

Want this handled for good?

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