How to Troubleshoot Missing or Incorrect Language Statistics in GitHub Readme Stats

Missing or incorrect language statistics in GitHub Readme Stats usually stem from API authentication issues, environment variable filters like EXCLUDE_REPO, or misconfigured query parameters such as hide or langs_count.

When your Top Languages card displays empty results, skewed percentages, or omits repositories you know contain specific languages, the issue typically lies in one of three pipeline stages. This guide walks you through diagnosing and fixing these problems using the actual implementation details from the anuraghazra/github-readme-stats repository.

Understanding the Language Statistics Pipeline

The card generation follows a strict three-stage pipeline defined in src/fetchers/top-languages.js and src/cards/top-languages.js.

Stage 1: Data Fetching

The fetchTopLanguages function sends a GraphQL query to GitHub's API, requesting every owned, non-fork repository and the first 10 languages per repository. The request is wrapped by the retryer utility (src/common/retryer.js) to handle transient network failures and rate-limit retries.

Stage 2: Data Processing

Raw responses are transformed into a flat language map. The system applies size weighting and count weighting to calculate percentages. It then filters out repositories listed in the EXCLUDE_REPO environment variable (defined in src/common/envs.js) and any repos supplied via the exclude query parameter. Finally, trimTopLanguages truncates the list to the desired langs_count while optionally hiding languages specified in the hide parameter.

Stage 3: Rendering

One of several layout renderers—renderNormalLayout, renderCompactLayout, renderDonutLayout, or renderPieLayout—builds the SVG fragments. Options such as hide_progress, layout, theme, and stats_format determine the final visual output.

Common Causes of Missing or Incorrect Statistics

API and Authentication Issues

If the card returns no data or throws an error, first verify your Personal Access Token (PAT). The fetcher requires Authorization: token <PAT> in the request header for private repositories and to avoid strict rate limits. If the token is missing or lacks the repo scope, GitHub returns a GraphQL error that the codebase converts into a CustomError (see src/common/error.js).

Additionally, if you request statistics for an organization instead of a user account, the fetcher throws CustomError.USER_NOT_FOUND because the GraphQL query targets user-owned repositories only.

Environment Variable Filters

The EXCLUDE_REPO variable (read in src/common/envs.js) silently removes matching repository names before language aggregation occurs. If a repository containing your dominant language is listed here, its contribution disappears from the chart without warning.

Similarly, if you deploy your own instance and configure WHITELIST or GIST_WHITELIST, ensure your username is permitted; otherwise, the request may be rejected before processing.

Query Parameter Misconfiguration

Several URL parameters directly affect output:

• hide: Accepts a comma-separated list of language names (case-insensitive). Accidentally including a language you want to display removes it from the card.
• langs_count: Overrides the default count (5 for normal layout). Setting this lower than your actual language diversity truncates the list.
• layout: Each layout has different defaults. For example, compact may display fewer languages by default than normal.
• hide_progress: When true, the card falls back to compact styling; combined with layout=compact, progress bars disappear, which can be mistaken for missing data.

Step-by-Step Troubleshooting Checklist

Follow these steps in order to isolate the issue:

1. Validate the GitHub Token

   • Ensure a PAT is supplied via the ?token= query string or the PAT_1 environment variable.
   • Verify the token includes the repo scope for private repositories.

2. Confirm the Username

   • The username parameter must target a user account, not an organization. Organizations trigger CustomError.USER_NOT_FOUND.

3. Inspect Environment Filters

   • Check EXCLUDE_REPO in your deployment's environment variables. Remove any repository that hosts languages you expect to see.
   • If using the public Vercel endpoint, verify your username is not blocked by WHITELIST restrictions.

4. Review Request Parameters

   • Remove the hide parameter temporarily to see all detected languages.
   • Increase langs_count (e.g., &langs_count=10) to ensure truncation isn't hiding data.
   • Set hide_progress=false and layout=normal to restore default visualization.

5. Examine the API Response

   • Test the endpoint directly with curl:

     curl "https://github-readme-stats.vercel.app/api/top-langs?username=YOUR_NAME"

   • Look for an errors array in the JSON response. Presence of errors triggers the error handling in src/common/error.js.

6. Check for Rate Limit or Retry Exhaustion

   • The retryer utility retries failed requests up to a configured limit. If you receive CustomError.MAX_RETRY, GitHub's rate limit has been exceeded. Wait or use a different PAT.

Code Examples for Common Scenarios

1. Basic usage – normal layout (default)

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs?username=octocat)

2. Excluding a language that you don't want to see

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&hide=HTML)

3. Using the compact layout and showing progress bars

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=compact&hide_progress=false)

4. Overriding the number of displayed languages

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&langs_count=10)

5. Supplying a personal access token (required for private repos)

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&token=YOUR_PERSONAL_ACCESS_TOKEN)

6. Local development – setting EXCLUDE_REPO

Create a .env file in the project root:

EXCLUDE_REPO=repo-to-ignore,another-repo

Then run the server:

npm start

The languages from the excluded repos will no longer affect the chart.

Key Source Files Reference

File	Role in language statistics
src/fetchers/top-languages.js	Sends the GraphQL query, filters excluded repos, aggregates and weights language data.
src/cards/top-languages.js	Renders the SVG for all supported layouts (normal, compact, donut, pie). Handles options like hide, layout, langs_count.
src/common/envs.js	Reads environment variables (EXCLUDE_REPO, WHITELIST, GIST_WHITELIST).
src/common/error.js	Defines CustomError and MissingParamError, provides secondary messages for API failures.
src/common/retryer.js	Implements exponential back‑off retries for the GitHub request.
src/common/Card.js	Base class that assembles the final SVG, applies theming, borders, and animation toggles.

Summary

• Authentication is critical: Missing or improperly scoped PATs cause CustomError responses and empty cards for private repositories.
• Environment filters hide data silently: Check EXCLUDE_REPO in src/common/envs.js if specific languages disappear unexpectedly.
• Query parameters control visibility: The hide, langs_count, and layout parameters directly determine which languages appear and how they are displayed.
• Rate limits trigger retry exhaustion: If you encounter CustomError.MAX_RETRY, GitHub's API rate limit has been exceeded; implement caching or use a different token.
• Three-stage pipeline: Issues can originate during data fetching (src/fetchers/top-languages.js), processing (trimTopLanguages), or rendering (src/cards/top-languages.js).

Frequently Asked Questions

Why are my most used languages not showing up in the GitHub Readme Stats card?

Your most used languages may be hidden due to the EXCLUDE_REPO environment variable filtering out repositories that contain those languages, or the hide query parameter may be suppressing them. Additionally, if you are using the langs_count parameter with a low value, the card truncates the list before reaching your dominant languages. Check src/fetchers/top-languages.js to see how the trimTopLanguages function applies these filters.

How do I include private repositories in my language statistics?

To include private repositories, you must supply a Personal Access Token (PAT) with the repo scope via the token query parameter or the PAT_1 environment variable. Without this token, the GraphQL query in src/fetchers/top-languages.js only returns public repository data, and private language statistics will be omitted entirely.

Why do the language percentages differ from GitHub's own statistics?

GitHub Readme Stats calculates percentages using a weighted aggregation of size and count metrics across your top repositories, whereas GitHub's native profile view uses different weighting algorithms and may include forks or archived repos that this tool excludes by default. Additionally, the size_weight and count_weight parameters in the processing stage can skew results differently than GitHub's native calculations.

What does the "Maximum retries exceeded" error mean when loading the language card?

This error (CustomError.MAX_RETRY defined in src/common/error.js) indicates that the retryer utility in src/common/retryer.js exhausted its exponential back-off attempts while trying to reach GitHub's API. This typically occurs when you have hit GitHub's rate limit due to insufficient authentication or high traffic. To resolve it, wait for the rate limit window to reset, supply a valid PAT to increase your quota, or deploy your own instance to avoid shared rate limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}