GitHub Actions "Failed to pull image" / invalid action URI in CI

By Kaveh Alemi·Latchkey

A Docker-based action runs from an image referenced by URI. A malformed docker:// reference, a private image without credentials, or a nonexistent tag makes the runner unable to find the action at that URI.

What this error means

A Docker-action step fails with "failed to pull image" or a message that the action could not be found at the given URI, before the container starts.

Error: Docker pull failed with exit code 1, back off ... retries left.
Error: failed to pull image "ghcr.io/acme/tool:nope":
manifest unknown

Common causes

A wrong image name or tag

The docker:// reference or image: in action.yml points to a tag that does not exist in the registry.

A private image without login

The image is private and the workflow did not authenticate to the registry before the action ran.

How to fix it

Reference a real, pullable image

1. Confirm the image and tag exist in the registry.
2. Log in to the registry before the Docker action if it is private.
3. Fix the docker:// URI or action.yml image.

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker://ghcr.io/acme/tool:1.2.3

Pin a digest for immutable images

Reference the image by @sha256:... so a deleted or re-pushed tag does not break the pull.

How to prevent it

• Verify image names and tags exist before using them.
• Authenticate to private registries before Docker actions.
• Pin images by digest where stability matters.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions