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

> Troubleshoot missing or incorrect language statistics in GitHub Readme Stats by checking API authentication, environment variables, and query parameters. Fix common issues and ensure accurate stats.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/fetchers/top-languages.js) and [`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`:
     ```bash
     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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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)

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

```

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

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

```

### 3. Using the compact layout and showing progress bars

```markdown
![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

```markdown
![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)

```markdown
![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:

```dotenv
EXCLUDE_REPO=repo-to-ignore,another-repo

```

Then run the server:

```bash
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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/fetchers/top-languages.js) | Sends the GraphQL query, filters excluded repos, aggregates and weights language data. |
| [`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/envs.js) | Reads environment variables (`EXCLUDE_REPO`, `WHITELIST`, `GIST_WHITELIST`). |
| [`src/common/error.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/error.js) | Defines `CustomError` and `MissingParamError`, provides secondary messages for API failures. |
| [`src/common/retryer.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/retryer.js) | Implements exponential back‑off retries for the GitHub request. |
| [`src/common/Card.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/fetchers/top-languages.js)), processing (`trimTopLanguages`), or rendering ([`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/error.js)) indicates that the `retryer` utility in [`src/common/retryer.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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.