docker/build-push-action "tag is needed when pushing to registry" (tags empty)

By Kaveh Alemi·Latchkey

When push: true, buildx needs at least one tag to name the pushed image. An empty tags input (often a metadata-action output that produced nothing) fails the build.

What this error means

The build-push step fails with "tag is needed when pushing to registry" or an empty tags error.

ERROR: tag is needed when pushing to registry
##[error]buildx failed with: ERROR: tag is needed when pushing to registry

Common causes

tags input is empty

No tags were provided, or the upstream metadata-action emitted an empty tags output.

Pushing without a destination

push: true with no fully qualified image:tag gives buildx nowhere to push.

How to fix it

Provide tags (directly or via metadata-action)

1. Set tags to a fully qualified image reference, or wire docker/metadata-action outputs.
2. Verify the metadata step produced non-empty tags.
3. Re-run the build.

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}
- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ${{ steps.meta.outputs.tags }}

How to prevent it

• Always pair build-push push:true with explicit tags or a metadata-action.
• Assert the metadata tags output is non-empty before pushing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions