badges/shields · error · NotFound

tag not found

Error message

tag not found

What it means

This NotFound error is thrown when a specific tag is requested from the Docker Hub version service but no entry in the Docker Hub tag-listing response has that exact name (data.find(d => d.name === tag) returns undefined). It means the repository does not contain a tag matching the requested name exactly. Being a NotFound, the badge renders 'tag not found' instead of a server error.

Source

Thrown at services/docker/docker-version.service.js:148

          prettyMessage: 'digest not found for latest tag',
        })
      }
      const { digest } = imageTag
      return { version: getDigestSemVerMatches({ data: pagedData, digest }) }
    } else if (!tag && sort === 'semver') {
      const matches = data
        .filter(d => d.images.some(image => image.architecture === arch))
        .map(d => d.name)
      if (matches.length === 0) {
        throw new InvalidResponse({
          prettyMessage: `no images found for arch ${arch}`,
        })
      }
      return { version: latest(matches) }
    } else {
      version = data.find(d => d.name === tag)
      if (!version) {
        throw new NotFound({ prettyMessage: 'tag not found' })
      }
      if (Object.keys(version.images).length === 0) {
        return { version: version.name }
      }
      const image = version.images.find(i => i.architecture === arch)
      if (!image) {
        throw new InvalidResponse({
          prettyMessage: 'digest not found for given tag',
        })
      }
      const { digest } = image
      return { version: getDigestSemVerMatches({ data, digest }) }
    }
  }

  async handle({ user, repo, tag }, { sort, arch }) {
    let data, pagedData

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the exact tag name on Docker Hub (tags are matched by exact string, not prefix).
  2. Check the repository's tags page for the current tag list; the tag may have been deleted.
  3. Use a floating tag (e.g. latest) or omit the tag to resolve versions dynamically.
  4. Update the README/badge URL after version upgrades.

Example fix

// before
/badge/docker/v/_/library/node/18
// after (correct exact tag)
/badge/docker/v/_/library/node/18-alpine
Defensive patterns

Strategy: validation

Validate before calling

// confirm the tag exists before requesting the badge
const res = await fetch(`https://hub.docker.com/v2/repositories/${user}/${repo}/tags/${tag}`);
if (res.status === 404) throw new Error(`tag ${tag} not found on ${user}/${repo}`);

Try / catch

try {
  const version = await dockerVersion({ user, repo, tag });
} catch (err) {
  if (err instanceof NotFound || err.message === 'tag not found') {
    // fall back to 'latest' or render a placeholder badge
  } else {
    throw err;
  }
}

Prevention

When it happens

Trigger: Requesting /docker/v/<user>/<repo>/<tag> where the tag string does not exactly match any tag name returned by the Docker Hub API for that repository.

Common situations: Typo or case mismatch in the tag name; requesting a tag that was deleted or replaced; version changed (e.g. old tag removed on release); omitting a suffix like -alpine or -slim; tag exists only under a different namespace.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/80a5fe7ccfdaae7d. Report an issue: GitHub.