Docker "RUN --mount=type=ssh" - "SSH agent not available" / "no ssh forwarded"

By Daniel Zoghalchali·Latchkey

A RUN --mount=type=ssh needs an SSH agent forwarded into the build with --ssh. BuildKit reports the agent is not available because either --ssh was not passed or no agent is running on the runner.

What this error means

A build that clones a private repo over SSH fails on the RUN --mount=type=ssh step with SSH agent not available or a downstream Permission denied (publickey). The Dockerfile is correct; the SSH socket was never forwarded.

docker build output

ERROR: failed to solve: SSH agent not available; make sure to use
"docker build --ssh default" and have an ssh-agent running
# or the clone itself fails: git@github.com: Permission denied (publickey)

Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

Terminal

# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .

Common causes

No --ssh passed to the build

The mount forwards an agent socket only when --ssh default (or --ssh id=...) is on the build command. Without it, the mount has no agent to expose.

No ssh-agent running on the runner

Even with --ssh default, there must be a live agent holding the key. A fresh CI shell has no agent until you start one and add the deploy key.

build-push-action ssh input missing

With docker/build-push-action, the ssh: input must request default; omitting it means no socket is forwarded.

How to fix it

Start an agent, add the key, and forward it

Load the deploy key into an agent, then pass --ssh default to the build.

Terminal

eval "$(ssh-agent -s)"
ssh-add - <<< "$DEPLOY_KEY"
docker build --ssh default .

Forward SSH in build-push-action

Use the action’s ssh-agent setup, then request the default socket.

.github/workflows/build.yml

- uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- uses: docker/build-push-action@v6
  with:
    ssh: default

Keep the build context small and deterministic

A missing .dockerignore sends node_modules, .git, and build output to the daemon, which is slow and can change layer hashes between environments.
A COPY of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
Multi-arch builds need buildx and QEMU set up explicitly; a plain docker build on an ARM runner silently produces an ARM image.

How to prevent it

Always pair RUN --mount=type=ssh with --ssh default and a running agent.
Load the deploy key into the agent before the build step.
Prefer SSH forwarding or build secrets over copying keys into the image.

Frequently asked questions

What causes Docker "RUN --mount=type=ssh"?

There are 3 common causes: no --ssh passed to the build, no ssh-agent running on the runner, and build-push-action ssh input missing. The mount forwards an agent socket only when --ssh default (or --ssh id=...) is on the build command.

How do I fix Docker "RUN --mount=type=ssh"?

There are 2 fixes depending on which cause you have: start an agent, add the key, and forward it and forward ssh in build-push-action. Work through them in order, since the first is the most common.

What does Docker "RUN --mount=type=ssh" actually mean?

A build that clones a private repo over SSH fails on the RUN --mount=type=ssh step with SSH agent not available or a downstream Permission denied (publickey).

How do I stop Docker "RUN --mount=type=ssh" happening again?

Always pair RUN --mount=type=ssh with --ssh default and a running agent. The prevention section lists 3 changes that keep it from recurring.