Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

SQL Server container exits when /var/opt/mssql is a host folder

Errorthe container starts and exits within seconds after adding -v host-folder:/var/opt/mssql

Short answer

SQL Server 2019 and later containers run as a non-root user. If you mount a host folder on /var/opt/mssql and that user cannot write to it, setup cannot copy its system files and the container exits. Give the folder to the right owner, switch to a named volume, or run the container as a user the folder allows.

  • Applies to SQL Server 2019, SQL Server 2022, Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the container logs and the owner of the host folder. The logs name the file that could not be written, and ls shows who owns the folder.

    docker logs sql1 | tail -n 30
    ls -ln ./mssql-data
  2. 2Match what you see, then jump to its fix

    1. 1Permission denied in docker logs, and the folder is owned by your user or by root with mode 755The host folder is not writable by the container userFix
    2. 2You only want the data to survive docker rm and do not need the files on the hostA bind mount is not needed, a named volume avoids the owner problemFix
    3. 3You set a folder owner for your own login, but the container still runs as the default userThe container runs as a user that does not match the folderFix

What does the error look like?

  • the container starts and exits within seconds after adding -v host-folder:/var/opt/mssql
  • docker logs shows a setup error about the files under /var/opt/mssql
  • the same docker run works without the -v flag

Cause 1 of 3

The host folder is not writable by the container user

1Check

SQL Server 2019 and later containers start as non-root. The non-root user needs read and write access to the mounted folder through its owner or through the root group.

ls -ln ./mssql-data

2Fix

Make the root group the owner with group write access, or make UID 10001 the owner. Both forms are documented.

sudo chgrp -R 0 ./mssql-data
sudo chmod -R g=u ./mssql-data
# or:
# sudo chown -R 10001:0 ./mssql-data

3Verify

Start the container again and wait for the startup lines in the log.

docker rm -f sql1
docker run -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD='YourStrong!Passw0rd' -p 1433:1433 --name sql1 -v "$PWD/mssql-data:/var/opt/mssql" -d mcr.microsoft.com/mssql/server:2022-latest
docker logs sql1 | tail -n 5

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 3

A bind mount is not needed, a named volume avoids the owner problem

1Check

A named volume is created and managed by Docker, so you do not set an owner by hand. The Microsoft configuration page documents it as the second persistence option.

docker volume ls

2Fix

Replace the host path with a volume name.

docker run -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD='YourStrong!Passw0rd' \
  -p 1433:1433 -v sqlvolume:/var/opt/mssql \
  -d mcr.microsoft.com/mssql/server:2022-latest

3Verify

The volume holds the data after the container is removed and re-created with the same volume name.

docker rm -f sql1
docker volume ls

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

The container runs as a user that does not match the folder

1Check

The security page documents the -u flag. The non-root container must run in the root group unless the mounted volume is accessible to the user you set.

docker exec sql1 id

2Fix

Run the container as the user (and group) that owns the folder. As a last resort, -u 0:0 runs it as root, which gives it all file permissions.

docker run -e ACCEPT_EULA=Y -e MSSQL_SA_PASSWORD='YourStrong!Passw0rd' \
  -u $(id -u):$(id -g) -v "$PWD/mssql-data:/var/opt/mssql" \
  -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest

3Verify

Check the user inside the container and the startup log.

docker exec sql1 id
docker logs sql1 | tail -n 5

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Prefer a named volume for local development; use a bind mount only when you must open the files on the host.
  • Create the data folder and set its owner before the first docker run, not after the first failure.
  • Keep the password policy in mind: at least eight characters from three of the four character sets.

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

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

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