What causes "gist not found" in badges/shields?

Verify the gist exists and is public at gist.github.com

badges/shields · error · NotFound

gist not found

Error message

gist not found

What it means

Thrown in GithubGistStarsService.transform when the GitHub GraphQL response contains no gist object under data.viewer.gist, meaning the authenticated viewer cannot see a gist with the given id. NotFound 'gist not found' is raised before reading stargazerCount.

Source

Thrown at services/github/gist/github-gist-stars.service.js:94

        }
      `,
      variables: {
        gistId,
      },
      schema,
    })
    return data
  }

  static transform({ data }) {
    const {
      data: {
        viewer: { gist },
      },
    } = data

    if (!gist) {
      throw new NotFound({ prettyMessage: 'gist not found' })
    }

    const {
      stargazerCount,
      url,
      name,
      owner: { login },
    } = gist

    const stargazers = `https://gist.github.com/${login}/${name}/stargazers`

    return { stargazerCount, url, stargazers }
  }

  async handle({ gistId }) {
    const data = await this.fetch({ gistId })
    const { stargazerCount, url, stargazers } =
      await this.constructor.transform({

View on GitHub (pinned to 766fd8bc89)

Solutions

Verify the gist exists and is public at gist.github.com
Use the correct gist id (the hex string in the gist URL) in the badge
If the gist is secret, make it public or ensure the configured token belongs to an account that can view it
Check the GitHub GraphQL API directly to confirm viewer.gist is non-null

Example fix

// before
/github/gists/not-a-real-id/stars
// after
/github/gists/aa5a315d61ae9438b18d/stars

Defensive patterns

Strategy: type-guard

Validate before calling

const res = await fetch(`https://api.github.com/gists/${gistId}`);if (res.status === 404) console.warn(`gist ${gistId} not visible or does not exist`);

Type guard

const gistExists = (data) => Boolean(data?.data?.viewer?.gist && typeof data.data.viewer.gist === 'object');

Try / catch

try { return await gistStarsBadge(gistId); } catch (e) { if (String(e.message).includes('gist not found')) { return renderBadge('gist unavailable'); } throw e; }

Prevention

Use the gist id (hex string), not the full gist URL, in badge requests
Confirm gists remain public; secret gists may be invisible to the badge server's token
Re-validate gist ids if badges break after gist deletion

When it happens

Trigger: Requesting a gist stars badge with a gist id that does not exist, is secret (invisible to the token's viewer), or was deleted — the GraphQL query resolves gist to null.

Common situations: Gist was deleted or made secret after the badge was set up; gist id copied incorrectly (the badge uses the id, not the full URL with username); token's account differs from the gist owner for secret gists.

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/534686ada21b81c5. Report an issue: GitHub.