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.
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.
Find the WORKDIR line in your Dockerfile that's missing the leading slash:
# 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 /.
Convert the relative path to an absolute path by adding a leading slash:
# Before (incorrect):
WORKDIR app
# After (correct):
WORKDIR /app# Before (incorrect):
WORKDIR usr/share/nginx/html
# After (correct):
WORKDIR /usr/share/nginx/htmlThe leading slash ensures Docker creates or navigates to the directory starting from the container's root filesystem.
If you're using multiple WORKDIR instructions to navigate into subdirectories, ensure the first one is absolute:
# 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/serverWhile subsequent WORKDIR instructions can be relative (they build on the previous WORKDIR), it's clearer to use absolute paths throughout.
Test that your Dockerfile builds successfully:
# 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.
If you're setting the working directory in docker-compose.yml, the same rule applies:
# 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:
- ./:/appThe working_dir option in Compose maps to Docker's --workdir flag, which also requires an absolute path.
Enable Docker's build checks to catch WORKDIR issues before they cause problems:
# 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:
# 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.
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:
WORKDIR /app # Sets /app as working directory
WORKDIR src # Now in /app/src
WORKDIR utils # Now in /app/src/utilsHowever, 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:
# Ignore the warning (not recommended)
# check=skip=WorkdirRelativePath
# Make it an error (recommended for CI)
# check=error=WorkdirRelativePathWindows containers:
For Windows containers, use Windows-style absolute paths:
# Windows container
WORKDIR C:\app
# or
WORKDIR /app # Also works in Windows containersCommon patterns:
# Node.js application
WORKDIR /usr/src/app
# Python application
WORKDIR /app
# Go application
WORKDIR /go/src/myapp
# Nginx static files
WORKDIR /usr/share/nginx/htmldockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec