Maaz Zindani

Loading the index…

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

A container will not start: mount path must be absolute

ErrorInvalid volume destination path: '.' mount path must be absolute

Short answer

The second half of a volume mapping is the path inside the container, and the daemon only accepts an absolute one. A dot, a bare folder name or a path starting with ./ on that side triggers this error. A mapping with only one path is also read as a container path. Put host path first, absolute container path second.

  • Applies to Docker Compose v2, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the mounts Compose will actually pass on. The target of each one must start with a slash.

    docker compose config | grep -B1 -A4 -E 'volumes:|target:'
  2. 2Match what you see, then jump to its fix

    1. 1invalid mount path: './data' (or '.', or 'data') mount path must be absoluteThe container side of the mapping is relativeFix
    2. 2The error names the very path you meant as the host folder, for example '.' or './data', and the entry has no colonOnly one path was written, so it became the container pathFix
    3. 3invalid mount path with a target: line in the file, not a short entryThe long syntax has a relative targetFix

What does the error look like?

  • Invalid volume destination path: '.' mount path must be absolute
  • invalid mount path: '.' mount path must be absolute

Cause 1 of 3

The container side of the mapping is relative

1Check

A short volume entry reads HOST:CONTAINER. Relative paths are allowed on the host side, where they should start with . or .., but the destination inside the container is validated as an absolute path and cannot be the root path alone. Look for entries such as .:., ./db:db or ./app:./app.

grep -n -A6 'volumes:' docker-compose.yml compose.yaml 2>/dev/null

2Fix

Keep the relative path on the left and give the container an absolute path on the right.

services:
  app:
    image: my-app:latest
    volumes:
      # wrong: - ./h2-data:h2-data
      - ./h2-data:/opt/h2-data

3Verify

The service starts and the folder is visible at the new path.

docker compose up -d
docker compose exec app ls /opt/h2-data

Confirmed by github.com

Did this fix it?

Cause 2 of 3

Only one path was written, so it became the container path

1Check

In -v and in the Compose short syntax the first field is optional. An entry with a single field has no source: it is taken as the destination inside the container and becomes an anonymous volume. Compose does not check that destination itself, so the engine rejects it. So - ./data is read as a container path, not a host one.

grep -n -A6 'volumes:' docker-compose.yml compose.yaml 2>/dev/null

2Fix

Add the missing half. To share the current folder, write the folder, a colon, then the absolute path where it should appear.

services:
  app:
    image: my-app:latest
    volumes:
      # wrong: - .
      - .:/app
# the same rule for docker run:
#   docker run -v "$(pwd)":/app my-app:latest

3Verify

Compose accepts the file, and the project files are listed inside the container.

docker compose config --quiet && echo OK
docker compose run --rm app ls /app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The long syntax has a relative target

1Check

In docker run --mount, the destination must be an absolute path. The engine checks the target of every mount the same way, so in the long Compose form the source may be relative and the target may not.

grep -n -A4 'type: bind' docker-compose.yml compose.yaml 2>/dev/null

2Fix

Keep source relative if you like, and make target absolute.

services:
  app:
    image: my-app:latest
    volumes:
      - type: bind
        source: ./config
        target: /etc/my-app

3Verify

The file parses without the error.

docker compose config --quiet && echo OK

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Read every volumes line as HOST:CONTAINER and check that the part after the colon starts with a slash.
  • Start every host path that is not a volume name with ./ or an absolute path, so it is never read as a name.
  • Run docker compose config --quiet in CI to catch a bad mapping before a deploy.

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.