# GitHub Actions docker/metadata-action Produces Empty Tags

> Fix docker/metadata-action emitting no tags - a missing images input, tag rules that match no event, or reading outputs.tags instead of the steps output.

Source: https://latchkey.dev/learn/github-actions/gha-docker-metadata-action-tags-empty  
Updated: 2026-06-25

docker/metadata-action generated no tags or labels, so the subsequent build/push has nothing to tag. Usually the images input is missing or the tag rules do not match the current event.

## Diagnose it: was the cache hit, and was it the right one?

Cache bugs split into three shapes and they need different fixes: the cache never saved, it saved but the key never matches on restore, or it restored a stale entry through a `restore-keys` prefix and is now poisoning the build. The step output tells you which one you have.

```.github/workflows/ci.yml
- uses: actions/cache@v4
  id: cache
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- name: What happened
  run: |
    echo "exact hit: ${{ steps.cache.outputs.cache-hit }}"
    echo "key used:  ${{ steps.cache.outputs.cache-matched-key }}"
```

> `cache-hit` is only `true` on an exact key match. A `restore-keys` prefix match reports `cache-hit: false` while still restoring files, which is exactly how a stale cache gets mistaken for no cache at all.

## Cache limits that produce confusing failures

- Repository cache is capped at 10 GB. Past that, GitHub evicts least-recently-used entries, so a large cache can silently stop persisting.
- Caches are scoped by branch. A cache written on a feature branch is not visible to another feature branch, only to its base and its own descendants.
- An entry not read for 7 days is evicted, so a rarely-run workflow effectively never has a warm cache.
- Restoring a cache built for a different tool version is worse than a cold start, because you get a corrupted tree instead of a clean install. Always include the tool version in the key.

## FAQ

### What causes GitHub Actions docker/metadata-action produces empty tags?

There are 2 common causes: missing images input and tag rules do not match the event. metadata-action needs the images input (the registry/repo) to construct tags.

### How do I fix GitHub Actions docker/metadata-action produces empty tags?

There are 2 fixes depending on which cause you have: provide images and explicit tag rules and match tag rules to the trigger. Work through them in order, since the first is the most common.

### What does GitHub Actions docker/metadata-action produces empty tags actually mean?

The metadata step succeeds but steps.meta.outputs.tags is empty, and docker/build-push-action either pushes an untagged image or fails because no tags were provided.

### How do I stop GitHub Actions docker/metadata-action produces empty tags happening again?

Always pass the images input to metadata-action. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt