Docker "COPY --chmod not supported" (old syntax) in CI

By Kaveh Alemi·Latchkey

COPY --chmod and ADD --chmod set file permissions during the copy, but the flag only exists under BuildKit with a modern Dockerfile frontend. Building with the legacy classic builder, or pinning an old # syntax= frontend, rejects the flag.

What this error means

A build fails at a COPY --chmod=... line with the parser reporting --chmod as unknown, or that it requires BuildKit.

Error response from daemon: the --chmod option requires BuildKit. Refer to https://docs.docker.com/go/buildkit/ to build images with BuildKit enabled

Common causes

The classic (non-BuildKit) builder is in use

DOCKER_BUILDKIT=0 or an old daemon falls back to the legacy builder, which never learned --chmod.

A pinned old Dockerfile frontend

A # syntax=docker/dockerfile:1.0 line uses a frontend that predates the --chmod flag.

How to fix it

Enable BuildKit and a current frontend

1. Set DOCKER_BUILDKIT=1 (or use docker buildx build).
2. Pin a recent # syntax=docker/dockerfile:1 line.

# syntax=docker/dockerfile:1
FROM alpine:3.20
COPY --chmod=755 entrypoint.sh /usr/local/bin/entrypoint.sh

Set permissions with a RUN chmod instead

1. If you cannot enable BuildKit, COPY the file then chmod it.
2. This works on the classic builder too.

COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod 755 /usr/local/bin/entrypoint.sh

How to prevent it

• Keep DOCKER_BUILDKIT=1 in CI so modern COPY flags work.
• Pin # syntax=docker/dockerfile:1 rather than an old frontend tag.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation