buildx "tag is needed when pushing to registry" / output requires push in CI

By Kaveh Alemi·Latchkey

When buildx exports to a registry (via --push or --output type=registry), it must know the target reference. Without a -t/--tag, there is no repository to push to, so buildx stops before building.

What this error means

A build with --push but no tag fails with "ERROR: tag is needed when pushing to registry". The image was never built because the destination is unknown.

ERROR: tag is needed when pushing to registry

Common causes

Pushing without a -t/--tag

--push is shorthand for --output type=registry, which needs a full image reference to push to.

A templated tag resolved to empty

A tag built from an action output or variable that was empty leaves the build with no reference.

How to fix it

Provide a fully qualified tag

1. Add -t registry/owner/image:tag to the build.
2. Confirm any templated tag resolves to a non-empty value.
3. Re-run the push.

docker buildx build --push \
  -t ghcr.io/acme/app:${{ github.sha }} .

Use docker/metadata-action for tags

Generate consistent tags and feed them into the build so the reference is never empty.

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/acme/app

How to prevent it

• Always pair --push with at least one -t tag.
• Validate templated tag values are non-empty before building.
• Generate tags with metadata-action for consistency.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation