Docker Compose "build secrets not supported in compose version" in CI

By Daniel Zoghalchali·Latchkey

Compose can forward secrets into a build via services.<svc>.build.secrets, but only with BuildKit and a recent Compose. On an older Compose or with the legacy builder, the build-secrets schema is unsupported and either rejected or silently ignored, so the RUN --mount=type=secret step fails.

What this error means

A docker compose build errors on build.secrets as an unknown/unsupported property, or the build secret never mounts and the step fails.

services.api.build Additional property secrets is not allowed

Common causes

An old Compose that lacks build.secrets

Compose v1 (and early v2) do not support the build.secrets schema.

BuildKit not enabled for the compose build

Build secrets require BuildKit; the classic builder cannot mount them.

How to fix it

Use a current Compose with BuildKit

1. Upgrade to a Compose v2 release that supports build.secrets.
2. Declare the top-level secret and reference it under the build.

services:
  api:
    build:
      context: .
      secrets:
        - npm_token
secrets:
  npm_token:
    file: ./npm_token.txt

Build with buildx and pass the secret directly

1. If you cannot use compose build secrets, build with buildx and --secret.

docker buildx build --secret id=npm_token,src=./npm_token.txt -t myorg/api:ci .

How to prevent it

• Pin a Compose v2 version that supports build.secrets.
• Keep BuildKit enabled so build-time secrets can mount.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation