badges/shields · error · NotFound

no releases found

Error message

no releases found

What it means

The downloads service's handle() fetches all releases (or a specific tagged release's set) and throws NotFound 'no releases found' when the resulting array is empty. Unlike error 103, no filter was involved in this path — the repository simply has no GitHub Releases to compute download totals from. This is a definitive 404-style condition for release-download badges.

Source

Thrown at services/github/github-downloads.service.js:192

    } else if (tag) {
      const wantedRelease = await this._requestJson({
        schema: releaseSchema,
        url: `/repos/${user}/${repo}/releases/tags/${tag}`,
        httpErrors: httpErrorsFor('repo or release not found'),
      })
      releases = [wantedRelease]
    } else {
      const allReleases = await this._requestJson({
        schema: releaseArraySchema,
        url: `/repos/${user}/${repo}/releases`,
        options: { searchParams: { per_page: 500 } },
        httpErrors: httpErrorsFor('repo not found'),
      })
      releases = allReleases
    }

    if (releases.length === 0) {
      throw new NotFound({ prettyMessage: 'no releases found' })
    }

    const { downloads } = this.constructor.transform({
      releases,
      assetName,
    })

    return this.constructor.render({
      tag,
      assetName,
      downloads,
      displayAssetName,
    })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Publish at least one GitHub Release for the repository (Releases > Draft a new release).
  2. Double-check the user/repo slug in the URL points at the intended repository.
  3. Use a different metric badge (e.g. stars) if the project intentionally has no releases.

Example fix

// before
/service/github/downloads/release/user/repo/total.json  (repo has no releases)
// after: create a release, or track stars instead
/service/github/stars/user/repo.json
Defensive patterns

Strategy: validation

Validate before calling

// ensure the repo has releases before requesting downloads
const rels = await fetch('https://api.github.com/repos/OWNER/REPO/releases?per_page=1').then(r => r.json());
if (!Array.isArray(rels) || rels.length === 0) throw new Error('repository has no GitHub releases');

Type guard

function hasReleases(releases) {
  return Array.isArray(releases) && releases.length > 0 && releases.every(r => r != null && typeof r.tag_name === 'string');
}

Try / catch

try {
  const { downloads } = await getDownloads({ user, repo, assetName });
} catch (e) {
  if (e.prettyMessage === 'no releases found') {
    // render an inactive badge or publish a release first
  } else throw e;
}

Prevention

When it happens

Trigger: Requesting a downloads badge for a repo that uses only git tags without formal GitHub Releases, or for a specific asset/tag that yields zero releases; also when a repo has zero published releases at all.

Common situations: Projects distributing binaries via CI artifacts or third-party hosts instead of GitHub Releases; freshly created repos; mistyping the repo name so you hit an empty/template repo.

Related errors

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