Docker "Dockerfile: unknown flag: link" in CI

By Daniel Zoghalchali·Latchkey

COPY --link writes the copy as an independent layer that does not depend on earlier filesystem state, which speeds up caching. The flag was added to the Dockerfile frontend in 1.4; an older frontend or the classic builder rejects it as "unknown flag: link".

What this error means

A build fails at parse time at a COPY --link ... line with dockerfile parse error: unknown flag: link.

Dockerfile:7
--------------------
   7 | >>> COPY --link ./app /app
--------------------
ERROR: failed to solve: dockerfile parse error on line 7: unknown flag: link

Common causes

An old Dockerfile frontend

A # syntax= pin below 1.4 (or no BuildKit) does not recognize --link.

The classic builder is active

DOCKER_BUILDKIT=0 routes the build through the legacy builder, which has no --link support.

How to fix it

Pin a frontend that supports --link

1. Add # syntax=docker/dockerfile:1 (resolves to a current frontend).
2. Build with BuildKit enabled.

# syntax=docker/dockerfile:1
FROM scratch
COPY --link ./app /app

Drop --link if you must use an old builder

1. Remove the --link flag; the copy still works, just without the layered-independence optimization.

COPY ./app /app

How to prevent it

• Pin # syntax=docker/dockerfile:1 to keep modern COPY flags available.
• Standardize CI on BuildKit so the frontend is current.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation