How to fix WORKDIR: path must be absolute in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 150 views

This error occurs when you use a relative path in a Dockerfile WORKDIR instruction without first establishing an absolute base path. Docker requires WORKDIR paths to start with a leading slash (/) to ensure predictable, portable builds.

Quick fix

Fixes WORKDIR: path must be absolute

# Problematic examples:
WORKDIR app                    # Missing leading slash
WORKDIR usr/share/nginx/html   # Missing leading slash
WORKDIR ./app                  # Relative path with ./
  1. Identify the problematic WORKDIR instruction
  2. Add the leading slash to make the path absolute
  3. Fix sequential WORKDIR instructions
  4. Verify your fix by building the image
docker — error
# Problematic examples:
WORKDIR app                    # Missing leading slash
WORKDIR usr/share/nginx/html   # Missing leading slash
WORKDIR ./app                  # Relative path with ./
WORKDIR: path must be absolute

What this error means

When Docker encounters "WORKDIR: path must be absolute," it means you've specified a directory path that doesn't start from the filesystem root. The WORKDIR instruction sets the working directory for subsequent RUN, CMD, ENTRYPOINT, COPY, and ADD instructions. Docker requires this path to be absolute (starting with `/`) because relative paths depend on the base image's working directory, which can change unexpectedly between image versions. Using a relative path like `WORKDIR app` or `WORKDIR usr/share/nginx/html` is problematic because: - The base image's WORKDIR could change in future versions - Different base images have different default working directories - It makes the build less predictable and harder to debug Docker's build checks flag this as a warning (WorkdirRelativePath) to help you write more maintainable Dockerfiles.

Typical symptoms

  • Docker build fails with 'WORKDIR: path must be absolute' error
  • Build check warning: WorkdirRelativePath in Dockerfile
  • VS Code Docker extension shows 'WORKDIR paths should be absolute' warning
  • CI/CD pipeline fails during image build step
  • Dockerfile linter flags WORKDIR instruction as invalid
  • Build works locally but fails in different environment due to base image differences

Common causes

  1. Missing leading slash (/) in WORKDIR path - e.g., WORKDIR app instead of WORKDIR /app
  2. Typo in path where leading slash was accidentally omitted
  3. Copy-paste error from documentation or examples that used relative paths
  4. Confusion between host paths and container paths
  5. Using WORKDIR to set a relative subdirectory without first setting an absolute base
  6. Migrating from a script that used cd commands with relative paths

How to fix "WORKDIR: path must be absolute"

1Identify the problematic WORKDIR instruction

Find the WORKDIR line in your Dockerfile that's missing the leading slash:

dockerfile
# Problematic examples:
WORKDIR app                    # Missing leading slash
WORKDIR usr/share/nginx/html   # Missing leading slash
WORKDIR ./app                  # Relative path with ./

Check your Dockerfile for any WORKDIR instruction that doesn't start with /.

2Add the leading slash to make the path absolute

Convert the relative path to an absolute path by adding a leading slash:

dockerfile
# Before (incorrect):
WORKDIR app

# After (correct):
WORKDIR /app
dockerfile
# Before (incorrect):
WORKDIR usr/share/nginx/html

# After (correct):
WORKDIR /usr/share/nginx/html

The leading slash ensures Docker creates or navigates to the directory starting from the container's root filesystem.

3Fix sequential WORKDIR instructions

If you're using multiple WORKDIR instructions to navigate into subdirectories, ensure the first one is absolute:

dockerfile
# Incorrect pattern:
WORKDIR app
WORKDIR server

# Correct pattern - first WORKDIR is absolute:
WORKDIR /app
WORKDIR server    # This is now relative to /app, resulting in /app/server

# Or use a single absolute path:
WORKDIR /app/server

While subsequent WORKDIR instructions can be relative (they build on the previous WORKDIR), it's clearer to use absolute paths throughout.

4Verify your fix by building the image

Test that your Dockerfile builds successfully:

bash
# Build the image
docker build -t myimage .

# Verify the WORKDIR was set correctly
docker run --rm myimage pwd
# Should output: /app (or your specified path)

If the build succeeds without warnings, you've fixed the issue.

5Fix WORKDIR in docker-compose.yml working_dir

If you're setting the working directory in docker-compose.yml, the same rule applies:

yaml
# Incorrect:
services:
  app:
    image: python:3.12-slim
    working_dir: app        # Missing leading slash

# Correct:
services:
  app:
    image: python:3.12-slim
    working_dir: /app       # Absolute path
    volumes:
      - ./:/app

The working_dir option in Compose maps to Docker's --workdir flag, which also requires an absolute path.

6Use build checks to catch this early

Enable Docker's build checks to catch WORKDIR issues before they cause problems:

bash
# Enable all build checks
docker build --check .

# Or set via environment variable
DOCKER_BUILDKIT=1 docker build .

You can also configure checks in your Dockerfile:

dockerfile
# syntax=docker/dockerfile:1
# check=error=WorkdirRelativePath

FROM nginx:alpine
WORKDIR /usr/share/nginx/html
COPY . .

This converts the warning into a build error, ensuring relative WORKDIR paths are caught immediately.

Advanced notes

Why Docker requires absolute paths:
Docker containers have their own isolated filesystem. When you use WORKDIR, you're specifying a location within that container filesystem. Absolute paths ensure the directory location is unambiguous regardless of what the base image's default working directory is.

Relative WORKDIR behavior (when it works):
If you first set an absolute WORKDIR, subsequent relative WORKDIR instructions will work by appending to the current path:

dockerfile
WORKDIR /app      # Sets /app as working directory
WORKDIR src       # Now in /app/src
WORKDIR utils     # Now in /app/src/utils

However, relying on relative paths for anything beyond the first WORKDIR can make Dockerfiles harder to understand at a glance.

Base image WORKDIR inheritance:
Your Dockerfile inherits the WORKDIR from its base image. For example:
- alpine starts with WORKDIR /
- node images may set WORKDIR to /app
- Official images can change their WORKDIR between versions

This is why starting with your own absolute WORKDIR is a best practice.

Build check configuration:
The WorkdirRelativePath check can be configured per-Dockerfile:

dockerfile
# Ignore the warning (not recommended)
# check=skip=WorkdirRelativePath

# Make it an error (recommended for CI)
# check=error=WorkdirRelativePath

Windows containers:
For Windows containers, use Windows-style absolute paths:

dockerfile
# Windows container
WORKDIR C:\app
# or
WORKDIR /app    # Also works in Windows containers

Common patterns:

dockerfile
# Node.js application
WORKDIR /usr/src/app

# Python application
WORKDIR /app

# Go application
WORKDIR /go/src/myapp

# Nginx static files
WORKDIR /usr/share/nginx/html

Frequently asked questions

What does "WORKDIR: path must be absolute" mean?
When Docker encounters "WORKDIR: path must be absolute," it means you've specified a directory path that doesn't start from the filesystem root. The WORKDIR instruction sets the working directory for subsequent RUN, CMD, ENTRYPOINT, COPY, and ADD instructions. Docker requires this path to be absolute (starting with /) because relative paths depend on the base image's working directory, which can change unexpectedly between image versions.
How do I fix "WORKDIR: path must be absolute"?
This error occurs when you use a relative path in a Dockerfile WORKDIR instruction without first establishing an absolute base path. Docker requires WORKDIR paths to start with a leading slash (/) to ensure predictable, portable builds.
What causes "WORKDIR: path must be absolute"?
Missing leading slash (/) in WORKDIR path - e.g., WORKDIR app instead of WORKDIR /app Typo in path where leading slash was accidentally omitted Copy-paste error from documentation or examples that used relative paths
Is the "WORKDIR: path must be absolute" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading