anuraghazra/github-readme-stats · error · CustomError

Could not render stats card.

Error message

Could not render stats card.

What it means

Thrown by renderStatsCard when the resulting card would be completely empty: every stat item has been filtered out via the 'hide' option AND the rank circle has been disabled via hide_rank. The five always-present stat keys are stars, commits, prs, issues, and contribs, so 'hide' must contain all of them (plus any 'show'-only keys) for statItems.length to reach 0. The library refuses to render a blank SVG and surfaces this CustomError with the secondary message 'Either stats or rank are required.'

Solutions

  1. Remove at least one stat from the hide list so statItems is non-empty (e.g. drop 'contribs' from hide).
  2. If you want a rank-only card, keep hide_rank=false (or omit it) and hide the stats instead — the rank circle alone renders fine.
  3. If you want a stats-only card, keep hide_rank=true but leave at least one of stars/commits/prs/issues/contribs visible.

Example fix

// before
// /api/?username=X&hide=stars,commits,prs,issues,contribs&hide_rank=true

// after (rank-only card is legal; just don't also hide rank)
// /api/?username=X&hide=stars,commits,prs,issues,contribs
// or keep at least one stat:
// /api/?username=X&hide=stars,commits,prs,issues&hide_rank=true
Defensive patterns

Strategy: validation

Validate before calling

// Validate render options before calling renderStatsCard.
const ALWAYS_ON_STATS = ["stars", "commits", "prs", "issues", "contribs"];
function validateStatsCardOptions({ hide = [], hide_rank = false, show = [] }) {
  const hideSet = new Set(hide);
  const visible = ALWAYS_ON_STATS.filter((k) => !hideSet.has(k));
  if (visible.length === 0 && hide_rank) {
    throw new Error(
      "Refusing to render an empty card: keep at least one stat, or set hide_rank=false for a rank-only card.",
    );
  }
}

Prevention

When it happens

Trigger: A GET /api/?username=X request that combines hide_rank=true with a hide query param listing every stat key, e.g. hide=stars,commits,prs,issues,contribs. Because the always-on keys are exactly {stars,commits,prs,issues,contribs}, hiding all five (and any extras surfaced via 'show') empties statItems; together with hide_rank=true the guard at stats.js:438 trips.

Common situations: A user copying a 'minimal card' snippet that hides stats to get a rank-only card, then separately toggling hide_rank=true; or a user iterating on hide= values until nothing remains. Also seen when a template sets hide='*' style lists without realizing rank is also disabled.

Related errors

AI-assisted analysis of anuraghazra/github-readme-stats@54a7985aee (2026-08-12). Data as JSON: /api/errors/6b4e0a5f694e03d3. Report an issue: GitHub.

Appendix: source

Thrown at src/cards/stats.js:439

      // create the text nodes, and pass index so that we can calculate the line spacing
      return createTextNode({
        icon: stats.icon,
        label: stats.label,
        value: stats.value,
        id: stats.id,
        unitSymbol: stats.unitSymbol,
        index,
        showIcons: show_icons,
        shiftValuePos: 79.01 + (isLongLocale ? 50 : 0),
        bold: text_bold,
        numberFormat: number_format,
        numberPrecision: number_precision,
      });
    });

  if (statItems.length === 0 && hide_rank) {
    throw new CustomError(
      "Could not render stats card.",
      "Either stats or rank are required.",
    );
  }

  // Calculate the card height depending on how many items there are
  // but if rank circle is visible clamp the minimum height to `150`
  let height = Math.max(
    45 + (statItems.length + 1) * lheight,
    hide_rank ? 0 : statItems.length ? 150 : 180,
  );

  // the lower the user's percentile the better
  const progress = 100 - rank.percentile;
  const cssStyles = getStyles({
    titleColor,
    ringColor,
    textColor,

View on GitHub (pinned to 54a7985aee)