Docker "failed to solve: WORKDIR creates invalid path" in CI

By Kaveh Alemi·Latchkey

A WORKDIR must resolve to a directory. When a component of the path already exists as a file or symlink to a non-directory, BuildKit cannot mkdir through it and the solve fails with creates an invalid path.

What this error means

A build fails at a WORKDIR instruction with creates an invalid path. A parent component of the WORKDIR exists as a file rather than a directory.

ERROR: failed to solve: WORKDIR /app/bin creates an invalid path: /app/bin is not a directory

Common causes

A path component already exists as a file

If /app/bin was created as a file (e.g. copied as a single binary), WORKDIR /app/bin/sub cannot make a directory under it.

A symlink in the path points at a non-directory

A WORKDIR whose parent is a symlink to a file resolves to an invalid directory target.

How to fix it

Use a path whose components are all directories

1. Pick a WORKDIR that does not collide with an existing file.
2. Create binaries under a directory rather than at the WORKDIR path itself.

# bin is a file here, so this fails:
# COPY app /app/bin
# WORKDIR /app/bin/run
# use distinct paths:
COPY app /app/bin/app
WORKDIR /app/work

Remove the conflicting file before WORKDIR

1. Delete or rename the file occupying the path.
2. Then set the WORKDIR.

RUN rm -f /app/bin
WORKDIR /app/bin

How to prevent it

• Keep WORKDIR paths distinct from file destinations.
• Avoid symlinking path components to non-directories.
• Name copied binaries explicitly rather than reusing a directory path.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation