Why Can’t You Use --chown with Copy --link in Docker?

Understanding the Incompatibility Between --chown and --link in Docker COPY Operations

Jun 24, 2025

In Docker, the --link flag was introduced to optimize image builds by creating deterministic, content-only layers. It focuses strictly on file content, not ownership or system state.

🔗 Official Docker Docs: --link

For an in-depth look at the pros and cons of COPY --link in Docker, check out my dedicated deep dive:

Think Twice Before Using COPY --link in Your Docker Builds

Kristiyan Velkov

May 21

Think Twice Before Using COPY --link in Your Docker Builds

Introduction

Read full story

So, what happens when you try to combine it with `--chown`?

Because --link runs the copy operation in an isolated layer, it doesn't have access to user databases like /etc/passwd from the base image. When you try:

COPY --link --chown=nginx:nginx ./my-content /usr/share/nginx/html

Docker will throw:

invalid user index: -1

It can’t find nginx because that user doesn’t exist in the isolated layer created by --link.

Best Practice: Use `COPY --link` with `USER`, Not `--chown`

When building Docker images, the cleanest and most efficient way to manage file permissions is to use COPY --link without --chown, and let the USER instruction handle access control. The --link flag ensures deterministic, content-only layers that are fast, cacheable, and reproducible. Adding --chown breaks this by requiring access to user metadata (e.g. /etc/passwd), which isn’t available in the isolated copy layer — causing build failures like invalid user index: -1.

Instead, structure your Dockerfile like this:

FROM nginx:stable

# Use content-only copy
COPY --link ./my-content /usr/share/nginx/html

# Set the user to run the container process
USER nginx

EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

This way:

Your build stays fast and deterministic.
The nginx user runs the process and can read the files.
You avoid unnecessary chown operations, which are often not needed for static assets.

If write access is required (rare for static content), skip --link and handle ownership explicitly using a RUN chown or runtime script — but only when necessary.

Keep it clean. Let Docker do what it’s good at.