badges/shields · error · NotFound

repository not found

Error message

repository not found

What it means

DockerSize.getSizeFromImageByLatestDate throws NotFound with prettyMessage 'repository not found' when the tags-by-date API response has data.count === 0, meaning Docker Hub listed zero tags for the requested repository. No tags means no latest image whose size could be reported.

Source

Thrown at services/docker/docker-size.service.js:142

  static defaultBadgeData = { label: 'image size', color: 'blue' }

  async fetch({ user, repo, tag, page }) {
    page = page ? `&page=${page}` : ''
    return await fetch(this, {
      schema: tag ? buildSchema : pagedSchema,
      url: `https://registry.hub.docker.com/v2/repositories/${getDockerHubUser(
        user,
      )}/${repo}/tags${
        tag ? `/${tag}` : '?page_size=100&ordering=last_updated'
      }${page}`,
      httpErrors: { 404: 'repository or tag not found' },
    })
  }

  getSizeFromImageByLatestDate(data, arch) {
    if (data.count === 0) {
      throw new NotFound({ prettyMessage: 'repository not found' })
    } else {
      const latestEntry = data.results[0]

      if (arch) {
        return { size: getImageSizeForArch(latestEntry.images, arch) }
      } else {
        return { size: latestEntry.full_size }
      }
    }
  }

  getSizeFromImageByLatestSemver(data, arch) {
    // If no tag is specified, and sorting is by semver, first filter out the entry containing the latest semver from the response with Docker images.
    // If no architecture is supplied by the user, return `full_size` from this entry.
    // If the architecture is supplied by the user, check if any of the returned images for this entry has an architecture matching the arch parameter supplied by the user.
    // If yes, return the size of the image with this arch.
    // If not, throw the `NotFound` error.

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the repository and at least one tag exist on Docker Hub
  2. Correct the user/repo spelling in the badge URL
  3. Make sure the repo is public or push a tag if you own it
  4. Check that the repo wasn't renamed/deleted; use the new namespace

Example fix

// before
/badge/docker/image-size/myuser/deleted-repo -> repository not found
// after
/badge/docker/image-size/myuser/existing-repo
Defensive patterns

Strategy: validation

Validate before calling

async function dockerRepoExists(user, repo) {
  const res = await fetch(`https://hub.docker.com/v2/repositories/${user}/${repo}/tags?page_size=1`)
  if (!res.ok) return false
  const data = await res.json()
  return (data.count ?? 0) > 0
}

Type guard

function repoHasImages(data) {
  return typeof data?.count === 'number' && data.count > 0
}

Try / catch

try {
  const size = await getDockerSizeBadge(user, repo)
} catch (err) {
  if (err.prettyMessage === 'repository not found') {
    size = null
  } else throw err
}

Prevention

When it happens

Trigger: Requesting a size badge (date-based path) for a user/repo whose tags listing returns count 0 - nonexistent namespace, deleted repo, private repo, or repo with zero pushes.

Common situations: Typos in namespace/repo; repos removed from Docker Hub; private images; newly created repos with no pushed tags.

Related errors

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