buildx "--mount=type=cache" invalid sharing / unsupported option in CI

By Daniel Zoghalchali·Latchkey

BuildKit parses each RUN --mount=type=cache flag strictly. An unknown key or a sharing value that is not shared, private, or locked makes the frontend reject the Dockerfile before the build starts.

What this error means

A build fails with "dockerfile parse error" or "unexpected key \"<key>\" in --mount" pointing at a RUN --mount=type=cache line, or rejects an invalid sharing= value.

ERROR: failed to solve: failed to parse stage definition:
unexpected key "share" in --mount (did you mean "sharing"?)

Common causes

A misspelled or unsupported mount key

A typo like share= instead of sharing=, or a key BuildKit does not recognize, fails the strict mount parser.

An invalid sharing value

sharing= accepts only shared, private, or locked; any other value is rejected.

How to fix it

Use valid mount keys and sharing values

1. Correct the key name (target, sharing, id, mode, uid, gid).
2. Set sharing to shared, private, or locked only.
3. Re-run the build once the mount syntax is valid.

RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
    pip install -r requirements.txt

Enable BuildKit so cache mounts are understood

Cache mounts require BuildKit; build through buildx or set DOCKER_BUILDKIT=1 so the syntax is supported.

DOCKER_BUILDKIT=1 docker build .

How to prevent it

• Use only documented --mount keys and sharing values.
• Build with BuildKit enabled so cache mounts parse.
• Lint the Dockerfile so mount typos are caught early.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation