# GitHub Readme Stats — User Guide

## 1. Quick Start

GitHub Readme Stats generates dynamic SVG cards that display GitHub
statistics (stars, commits, language usage, pinned repos, gists, WakaTime
time-tracking) for embedding directly in your README. Each card is rendered
server-side as an SVG and served through five Vercel serverless endpoints.
The cards animate on load, support 70+ themes, and respond to a rich set of
URL query parameters.

**Key features:**

- Stats card with rank circle, total stars, commits, PRs, issues, reviews
- Pinned repository card (single repo, with stars, forks, and language)
- Top languages card with five layouts (`normal`, `compact`, `donut`,
  `donut-vertical`, `pie`)
- WakaTime time-tracking card (per-language coding time, two layouts)
- Gist preview card
- 70+ built-in themes including `dark`, `radical`, `tokyonight`, `dracula`,
  `gruvbox`, `nord`, `catppuccin_mocha`, `github_dark`, plus per-element
  color overrides
- 50+ locales for card titles and stat labels
- Tunable cache control via the `cache_seconds` query parameter
- Rank algorithm computed in-card (no external rank service)

**Prerequisites:** any place that renders Markdown and embeds external
SVGs (GitHub README, GitLab, GitHub profile, Hashnode, Dev.to, personal
site).

**One-line usage** — embed the stats card for any GitHub username:

```markdown
![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)
```

The hosted instance lives at `https://github-readme-stats.vercel.app`.

> [!TIP]
> All five card endpoints follow the same shape — `https://github-readme-stats.vercel.app/api/<endpoint>?username=<your-handle>`.
> Once you know the parameter pattern you can compose any card variant from
> the URL alone, no client code required.

**What to try next:**

- Pick a theme from the catalog in section 4
- Hide stats you don't care about with `hide=`
- Switch the language card to donut or pie with `layout=`
- Self-host the API on your own Vercel account if you want unlimited rate

---

## 2. Installation

GitHub Readme Stats is consumed in two modes:

1. **As a remote SVG** — the typical case. You embed an `<img>` URL in
   Markdown. No installation, no dependencies. Skip to section 3.
2. **As a self-hosted API** — fork the repo, deploy to Vercel (or run the
   bundled Express adapter), set a GitHub Personal Access Token, point your
   README at your own domain. This section covers that path.

### 2.1 System requirements

| Requirement | Value |
|---|---|
| Node.js | `>=22` (declared in `package.json` engines) |
| Hosting | Vercel serverless (recommended) or any Node host that runs `express.js` |
| GitHub PAT | At least one `PAT_1`; multiple PATs (`PAT_1`, `PAT_2`, ...) are rotated automatically |
| Memory per function | 128 MB (set in `vercel.json`) |
| Function timeout | 10 seconds (set in `vercel.json`) |

### 2.2 Self-host on Vercel

=== "Fork + Deploy"
    ```bash
    # 1. Fork https://github.com/anuraghazra/github-readme-stats on GitHub
    # 2. In your fork's Vercel project, set environment variables:
    #    PAT_1 = ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    # 3. Deploy. Vercel auto-detects api/*.js and exposes the endpoints.
    ```

=== "Local Express server"
    ```bash
    git clone https://github.com/anuraghazra/github-readme-stats.git
    cd github-readme-stats
    npm install
    echo "PAT_1=ghp_yourpat" > .env
    node express.js
    ```

    ```text
    Server running on port 9000
    ```

The Express adapter exposes the same five routes under `/api`:

| Method | Path | Card |
|---|---|---|
| GET | `/api` | Stats card |
| GET | `/api/pin` | Pinned repository card |
| GET | `/api/top-langs` | Top languages card |
| GET | `/api/wakatime` | WakaTime card |
| GET | `/api/gist` | Gist card |

### 2.3 Verify your install

```bash
curl "http://localhost:9000/api?username=anuraghazra" -o stats.svg
file stats.svg
```

```text
stats.svg: SVG Scalable Vector Graphics image
```

If the response says `Missing params "username"`, your route is working
but you forgot the query string. If you see `No GitHub API tokens found`,
your `.env` was not loaded — see section 6.

> [!IMPORTANT]
> The official public instance lives at `github-readme-stats.vercel.app`.
> It is shared and rate-limited. If your card stops loading on a
> high-traffic README, host your own — that is the official recommendation
> in the in-card error secondary message: *"You can deploy own instance or
> wait until public will be no longer limited"*.

> [!WARNING]
> Tokens must be classic Personal Access Tokens with `public_repo` scope
> (or `repo` for private contributions). The fine-grained token model is
> not referenced in the source — stick with classic PATs.

### 2.4 Configuration via environment variables

Self-hosted deployments read the following environment variables:

| Variable | Purpose |
|---|---|
| `PAT_1`, `PAT_2`, ... | GitHub Personal Access Tokens. Rotated on rate-limit. At least one required. |
| `CACHE_SECONDS` | Override per-request `cache_seconds` for every card on this instance. |
| `WHITELIST` | Comma-separated list of GitHub usernames allowed to render. If set, all other usernames see "This username is not whitelisted". |
| `GIST_WHITELIST` | Same idea, for `/api/gist?id=...`. |
| `EXCLUDE_REPO` | Comma-separated list of repository names excluded from stats and language calculations on every request. |
| `FETCH_MULTI_PAGE_STARS` | Set to `"true"` to fetch repos beyond the first 100-star page when computing total stars. Off by default for public-instance rate-limit safety. |
| `NODE_ENV` | Set to `development` to disable cache headers entirely; set to `test` to disable animations and rate-limit retry counts. |
| `PORT` (or `port`) | Port for the Express adapter. Defaults to `9000`. |

> [!NOTE]
> `WHITELIST`, `GIST_WHITELIST`, and `EXCLUDE_REPO` are split on commas.
> There is no JSON form; one string, comma-separated, no spaces.

---

## 3. Configuration

GitHub Readme Stats has no config file. Every setting is a URL query
parameter, applied per card. The full reference is in section 4; here is
the minimum you need to think about up front.

### 3.1 The five endpoints

```text
https://github-readme-stats.vercel.app/api?username=USERNAME
https://github-readme-stats.vercel.app/api/pin?username=USERNAME&repo=REPO
https://github-readme-stats.vercel.app/api/top-langs?username=USERNAME
https://github-readme-stats.vercel.app/api/wakatime?username=USERNAME
https://github-readme-stats.vercel.app/api/gist?id=GIST_ID
```

Every endpoint returns `Content-Type: image/svg+xml`. Errors render as a
"Something went wrong!" card so your README never breaks.

### 3.2 Universal options

These parameters work on every card:

| Parameter | Type | Notes |
|---|---|---|
| `theme` | string | Theme name from the catalog in section 4. Falls back to `default`. |
| `title_color` | hex (no `#`) | Override card title color. Example: `title_color=fe428e`. |
| `text_color` | hex (no `#`) | Override stat/text color. |
| `icon_color` | hex (no `#`) | Override icon stroke color. |
| `bg_color` | hex (no `#`) or gradient | `bg_color=000` or `bg_color=90,fffefe,fff,000` (angle then 2+ hex codes). |
| `border_color` | hex (no `#`) | Override card border color. |
| `border_radius` | number | Card corner radius in pixels. Default `4.5`. |
| `hide_border` | bool | `true` removes the card border entirely. |
| `hide_title` | bool | `true` removes the card title row. |
| `cache_seconds` | int | Override TTL. Clamped per card type — see section 5. |
| `locale` | string | Localize the card title and stat labels (e.g., `locale=fr`). |
| `disable_animations` | bool | Disable fade-in / slide-in / rank-circle animations. |

> [!TIP]
> Boolean parameters accept the strings `true` and `false`
> (case-insensitive). Anything else is treated as undefined, falling back
> to the default. So `hide_border=1` will not work — use
> `hide_border=true`.

---

## 4. Core Usage

### 4.1 Stats card — `/api`

The flagship card. Shows a rank circle on the left and a stats column on
the right.

```markdown
![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)
```

#### What it shows by default

- Total Stars Earned
- Total Commits (last year)
- Total PRs
- Total Issues
- Contributed to (last year)

#### Stats card-specific parameters

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `username` | string | required | GitHub login |
| `hide` | csv list | `[]` | Hide specific stats. Valid keys: `stars`, `commits`, `prs`, `issues`, `contribs`, `prs_merged`, `prs_merged_percentage`, `reviews`, `discussions_started`, `discussions_answered`. |
| `show` | csv list | `[]` | Add optional stats that are off by default: `prs_merged`, `prs_merged_percentage`, `reviews`, `discussions_started`, `discussions_answered`. |
| `show_icons` | bool | `false` | Render an icon next to each stat row. |
| `hide_rank` | bool | `false` | Hide the rank circle. |
| `rank_icon` | enum | `default` | `default` shows the letter rank (S/A+/A/.../C). `github` shows the Octocat. `percentile` shows "Top X%". |
| `include_all_commits` | bool | `false` | Use the GitHub Search API to count ALL commits (not just last year). |
| `commits_year` | int | unset | Restrict commit count to a single year. |
| `line_height` | int | `25` | Vertical spacing between stat rows. |
| `card_width` | int | auto | Override total card width in px. |
| `text_bold` | bool | `true` | Bold the stat values. |
| `ring_color` | hex | theme | Override the rank circle stroke color. |
| `custom_title` | string | computed | Replace `"<Name>'s GitHub Stats"` with your own. |
| `number_format` | enum | `short` | `short` produces `1.2k`. `long` produces `1234`. |
| `number_precision` | int | `1` | Decimal places for `k` formatting. Clamped 0..2. |
| `exclude_repo` | csv list | `[]` | Hide specific repos from the star count. |

**Rank algorithm.** The rank letter (S, A+, A, A-, B+, B, B-, C+, C) is
computed in-card from your commits, PRs, issues, reviews, stars, and
followers using a weighted exponential-CDF / log-normal-CDF combination.
Weights are: stars 4, PRs 3, commits 2, issues 1, reviews 1, followers 1.
The percentile shown when `rank_icon=percentile` is the same value used
to pick the letter.

#### Recipe — show merged PRs and reviews, hide issues

```markdown
![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show=prs_merged,prs_merged_percentage,reviews&hide=issues)
```

#### Recipe — count all commits ever, with icons and a custom title

```markdown
![Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&include_all_commits=true&show_icons=true&custom_title=My+GitHub+Highlights)
```

> [!NOTE]
> `include_all_commits=true` triggers a separate REST call to
> `https://api.github.com/search/commits` (Cloak preview header). It
> costs an extra GitHub API hit per render and is more likely to
> rate-limit on high-traffic READMEs.

### 4.2 Pinned repo card — `/api/pin`

```markdown
![Repo](https://github-readme-stats.vercel.app/api/pin?username=anuraghazra&repo=github-readme-stats)
```

| Parameter | Type | Notes |
|---|---|---|
| `username` | string | required, GitHub login |
| `repo` | string | required, repository name (no owner prefix) |
| `show_owner` | bool | If `true`, the title is `owner/repo`; otherwise just `repo`. |
| `description_lines_count` | int | Clamped 1..3. Default 3. |

The card uses theme `default_repocard` if you don't pass `theme=`.
Archived and template repos render a small badge in the top-right.

> [!WARNING]
> Private repositories return `User Repository Not found` (or
> `Organization Repository Not found`). The fetcher explicitly checks
> `isPrivate` and refuses to render them regardless of token scope.

### 4.3 Top languages card — `/api/top-langs`

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=anuraghazra&layout=donut)
```

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `username` | string | required | |
| `layout` | enum | `normal` | One of `normal`, `compact`, `donut`, `donut-vertical`, `pie`. Anything else returns "Incorrect layout input". |
| `langs_count` | int | layout-dependent | Clamped 1..20. Defaults: 5 for normal/donut, 6 for compact/pie/donut-vertical. |
| `hide` | csv list | `[]` | Hide languages by name (case-insensitive, trimmed). |
| `exclude_repo` | csv list | `[]` | Drop repos before language aggregation. |
| `size_weight` | number | `1` | Exponent on byte size in the comparison index. |
| `count_weight` | number | `0` | Exponent on repo count in the comparison index. Increase to favour breadth over depth. |
| `hide_progress` | bool | `false` | Hide the progress bar in `compact` layout (label-only). |
| `stats_format` | enum | `percentages` | `percentages` shows `42.50%`. `bytes` shows `12.3 MB`. Anything else returns "Incorrect stats_format input". |
| `card_width` | int | `300` | Min `280`. Donut adds 50 px of padding internally. |

#### Layout previews

| Layout | Default langs | Best for |
|---|---|---|
| `normal` | 5 | Side-by-side bar list, plenty of space |
| `compact` | 6 | Single horizontal stacked bar with names beneath |
| `donut` | 5 | Bar list + donut chart on the right |
| `donut-vertical` | 6 | Donut on top, names below |
| `pie` | 6 | Solid pie wedges + names below |

> [!TIP]
> When you score a `0%` language that you'd rather not show, use
> `hide=html,css` (comma-separated, no spaces). Names are matched
> case-insensitively.

### 4.4 WakaTime card — `/api/wakatime`

```markdown
![Wakatime](https://github-readme-stats.vercel.app/api/wakatime?username=anuraghazra)
```

| Parameter | Type | Notes |
|---|---|---|
| `username` | string | WakaTime username (NOT GitHub) |
| `api_domain` | string | Override the WakaTime host. Default `wakatime.com`. Useful for self-hosted Wakapi instances. |
| `layout` | enum | `compact` for a stacked progress bar, otherwise the default per-language list. |
| `langs_count` | int | Number of languages to render. Defaults to all returned by WakaTime. |
| `hide` | csv list | Hide specific languages by name. |
| `display_format` | enum | `time` (e.g., `4 hrs 12 mins`) or `percent` (e.g., `42.30 %`). Default `time`. |
| `hide_progress` | bool | Hide the progress bars in default layout. |
| `line_height` | int | Default `25`. |
| `card_width` | int | Default `495`. Min `250` (or `400` in compact). |

The card auto-detects three "no data" states and renders the appropriate
text: `WakaTime user profile not public`, `User doesn't publicly share
detailed code statistics`, or `No coding activity this week`.

> [!CAUTION]
> Free public WakaTime profiles return time data only when the profile is
> set to public AND "Show code stats publicly" is enabled. Without both,
> the card renders one of the no-data messages.

### 4.5 Gist card — `/api/gist`

```markdown
![Gist](https://github-readme-stats.vercel.app/api/gist?id=YOUR_GIST_ID)
```

| Parameter | Type | Notes |
|---|---|---|
| `id` | string | required, GitHub gist ID (the long hex from the gist URL) |
| `show_owner` | bool | If `true`, the title is `owner/filename`; otherwise just the first filename. |

The card shows the gist's primary language (calculated as the largest
file by bytes), star count, and fork count. Description wraps to up to
10 lines; longer text is truncated with `...`.

### 4.6 Themes — full catalog

The repository ships **74** built-in themes. Pick by name with
`?theme=<name>`. Names are case-sensitive.

**Light themes:** `default`, `default_repocard`, `transparent`,
`gruvbox_light`, `solarized-light`, `buefy`, `vue`, `flag-india`,
`graywhite`, `swift`, `rose`, `catppuccin_latte`.

**Dark themes (popular):** `dark`, `radical`, `merko`, `gruvbox`,
`tokyonight`, `onedark`, `cobalt`, `cobalt2`, `synthwave`, `dracula`,
`prussian`, `monokai`, `nord`, `nightowl`, `github_dark`,
`github_dark_dimmed`, `aura_dark`, `panda`, `noctis_minimus`, `aura`,
`apprentice`, `material-palenight`, `gotham`, `bear`, `ayu-mirage`,
`solarized-dark`, `darcula`, `one_dark_pro`, `rose_pine`,
`catppuccin_mocha`, `omni`, `react`, `holi`, `neon`, `blue_navy`,
`calm_pink`, `calm`, `discord_old_blurple`, `outrun`, `ocean_dark`,
`city_lights`, `algolia`, `slateorange`, `kacho_ga`, `yeblu`, `blueberry`,
`chartreuse-dark`, `vue-dark`, `shades-of-purple`, `great-gatsby`,
`vision-friendly-dark`, `midnight-purple`, `shadow_red`, `shadow_green`,
`shadow_blue`, `jolly`, `maroongold`, `highcontrast`, `codeSTACKr`,
`date_night`, `moltack`, `ambient_gradient`.

**Gradient backgrounds** are supported. The theme `ambient_gradient`
ships with a multi-stop gradient. To make your own, set
`bg_color=<angle>,<color1>,<color2>[,<color3>...]` — for example
`bg_color=90,fffefe,fff,000`. The first value is the rotation angle in
degrees; the remaining hex codes (no `#`) are evenly spaced gradient
stops.

> [!NOTE]
> Issue #4765 tracked an older crash when a non-existent theme name was
> passed; that was fixed by the current `default` fallback. If your custom
> theme name produces a "Something went wrong" card, double-check spelling
> and capitalization.

---

## 5. Common Tasks

### 5.1 Embed a basic stats card

```markdown
![GitHub Stats](https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE)
```

### 5.2 Side-by-side stats and languages

```markdown
<a href="https://github.com/YOUR_HANDLE">
  <img height=180 src="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&theme=tokyonight&show_icons=true" />
  <img height=180 src="https://github-readme-stats.vercel.app/api/top-langs?username=YOUR_HANDLE&theme=tokyonight&layout=compact" />
</a>
```

The trick is wrapping both `<img>` tags in a single `<a>` and pinning
equal heights so they line up. Use raw HTML in your README — Markdown
image syntax doesn't permit attributes.

### 5.3 Match your README to a theme

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&theme=tokyonight&hide_border=true&bg_color=00000000)
```

`bg_color=00000000` (8-digit hex with alpha 0) makes the card transparent,
letting the GitHub README background show through. The shipped
`transparent` theme uses the same trick (`bg_color: ffffff00`).

### 5.4 Drop unwanted stats

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&hide=issues,contribs)
```

You can hide any subset of `stars`, `commits`, `prs`, `issues`, `contribs`,
`prs_merged`, `prs_merged_percentage`, `reviews`, `discussions_started`,
`discussions_answered`. Hiding everything AND setting `hide_rank=true`
returns a "Could not render stats card" error — there has to be at least
one stat or the rank circle.

### 5.5 Show your TRUE total commit count

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&include_all_commits=true)
```

Default behaviour counts only the last year (GitHub's GraphQL
`contributionsCollection` window). Set `include_all_commits=true` and the
card calls the REST search-commits endpoint to total every commit you've
ever authored.

### 5.6 Show only commits from a specific year

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&commits_year=2025)
```

The card label updates to `Total Commits (2025)`. Combine with `hide=` to
build a clean "annual recap" card.

### 5.7 Use the rank circle as a percentile

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&rank_icon=percentile)
```

Replaces the letter (S, A+, ..., C) with `Top 12.3%` — the same percentile
the letter is derived from.

### 5.8 Combine custom colors with a theme

Theme colors are defaults. Any explicit color parameter overrides the
theme:

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&theme=dracula&title_color=ff79c6&icon_color=8be9fd)
```

The colour parameters (`title_color`, `text_color`, `icon_color`,
`bg_color`, `border_color`, plus `ring_color` for the stats rank circle)
all accept 3, 4, 6, or 8-digit hex without the `#`.

### 5.9 Force a longer cache

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&cache_seconds=86400)
```

Per-card minimum and maximum:

| Card | Min | Default | Max |
|---|---|---|---|
| Stats | 12 hours | 1 day | 2 days |
| Top languages | 2 days | 6 days | 10 days |
| Pinned repo | 1 day | 10 days | 10 days |
| Gist | 1 day | 2 days | 10 days |
| WakaTime | 12 hours | 1 day | 2 days |

Values you pass via `cache_seconds` are clamped to the per-card range
above. `cache_seconds=999999999` will not actually cache for that long;
it will be capped at the card's max.

> [!IMPORTANT]
> GitHub's image proxy (Camo) caches images aggressively. Even when the
> upstream `Cache-Control` says one day, GitHub may not refetch for
> several hours after the first render. To force a refresh you usually
> need to alter the URL (add a dummy `&v=2` parameter) on the README side.

### 5.10 Localize the card

```markdown
![](https://github-readme-stats.vercel.app/api?username=ME&locale=de)
```

50+ locales are supported. Common ones: `en`, `es`, `fr`, `de`, `pt-br`,
`pt-pt`, `ja`, `cn`, `zh-tw`, `kr` (Korean), `it`, `ru`, `nl`, `pl`, `tr`,
`vi`, `id`, `ar`, `hi`, `bn`, `fa`, `he`, `th`, `uk-ua`, `fil`, `sw`,
`cs`, `sk`, `bg`, `el`, `ro`, `ca`, `fi`, `se` (Swedish), `no` (Norwegian),
`np` (Nepali), `ml`, `my`, `ta`, `ur`, `sa`, `sr`, `sr-latn`, `uz`, `az`,
`hu`, `ml`. Unrecognised locales render a "Language not found" /
"Locale not found" error card.

### 5.11 Pin a self-hosted instance

After deploying your fork, replace every `github-readme-stats.vercel.app`
URL in your README with `your-project.vercel.app` (or your custom domain).
Same query string, same parameters.

---

## 6. Troubleshooting

### Error: `Missing params "username" make sure you pass the parameters in URL`

**Cause:** You opened the API URL without a `?username=` query string.

**Solution:**

1. Add `?username=YOUR_HANDLE` to the URL.
2. For `/api/pin`, also add `&repo=REPO_NAME`.
3. For `/api/gist`, use `?id=GIST_ID` instead.

**Prevention:** Always copy the URL from a working README rather than
typing it out.

### Error: `No GitHub API tokens found`

**Cause:** Self-hosted instance has no `PAT_*` env var set.

**Solution:**

1. Generate a classic Personal Access Token at
   `https://github.com/settings/tokens`. Scope: `public_repo` for public
   stats, `repo` if you want private contributions counted.
2. Set `PAT_1=ghp_xxxxxxxxxxxxxxxxxxxx` in Vercel project settings (or
   `.env` for local).
3. Redeploy.

**Prevention:** Add at least two PATs (`PAT_1`, `PAT_2`). The retryer
rotates through them on rate-limit, dramatically increasing your
effective request budget.

### Error: `Downtime due to GitHub API rate limiting`

**Cause:** Every PAT in your environment hit the rate limit.

**Solution:**

1. Wait until the next reset window (the in-card error secondary message
   reads *"You can deploy own instance or wait until public will be no
   longer limited"*).
2. Self-host with multiple PATs.
3. Hit `/api/status/pat-info` on your own instance to see which PATs are
   exhausted/expired.

**Prevention:** Provision PAT_1 through PAT_5 if your README is on a
high-traffic profile. Increase `cache_seconds` (capped at the per-card max).

### Error: `User Repository Not found` (or `Organization Repository Not found`)

**Cause:** Either the repo doesn't exist, or it's marked private. The
fetcher explicitly refuses private repos regardless of token scope.

**Solution:**

1. Verify spelling — `repo=` is the bare name, no `owner/` prefix.
2. Check the repo's GitHub settings; toggle to public if appropriate.
3. For organisation-owned repos, GitHub's GraphQL returns the org
   wrapper — pass `username=ORG_LOGIN`. The card walks both `user` and
   `organization` paths automatically.

**Prevention:** Use `/api/pin` only for public repos.

### Error: `Gist not found`

**Cause:** The gist ID is wrong, or the gist is secret.

**Solution:** Copy the ID from `https://gist.github.com/USER/GIST_ID`.
Public gists only.

### Error: `Could not resolve to a User with the login of '<username>'`

**Cause:** WakaTime endpoint received a username that WakaTime doesn't
recognise.

**Solution:**

1. Confirm the user has a public WakaTime profile (or a public Wakapi
   profile if you set `api_domain=`).
2. Visit `https://wakatime.com/@USER` directly to verify.

**Prevention:** Use the WakaTime username, NOT the GitHub username. They
are usually the same, but not always.

### Error: `Invalid username provided.`

**Cause:** You set `include_all_commits=true` and the username failed
GitHub's username regex (the project uses the `github-username-regex`
package).

**Solution:** Drop `include_all_commits` or fix the username spelling.

### Card stops loading on a popular README — issue #1406, #4798, #4858

**Cause:** GitHub's Camo proxy is caching a stale error response, or the
public Vercel instance is rate-limited (issues #4867 / #3851 / #4864
track "DEPLOYMENT_PAUSED" errors when the public Vercel instance hits
its serverless quota).

**Solution:**

1. Force a Camo refresh: append `&v=2` (or any dummy parameter) to the
   URL in your README.
2. Switch your README to a self-hosted fork.
3. Wait a few hours and retry.

**Prevention:** Self-hosting is the durable fix. The public instance is
shared by millions of READMEs; rate-limit churn is constant.

### Languages card returns "Incorrect layout input"

**Cause:** `layout=` was set to a value other than the five supported
ones.

**Solution:** Use exactly one of `normal`, `compact`, `donut`,
`donut-vertical`, `pie`. Any typo (`donat`, `peei`) is rejected
explicitly.

### `Translation string not found` or `'<key>' translation not found for locale`

**Cause:** The card asked the I18n module for a key that doesn't exist
in the requested locale. Usually means you passed a malformed `locale=`
or you're rendering through a fork that's missing translations.

**Solution:** Use `locale=en` to confirm the card otherwise works, then
pick a supported locale from section 5.10.

### Repository pin description overflows — issue #4862

**Cause:** Long descriptions are truncated to three lines by default. If
yours runs longer, the last line shows `...` truncation.

**Solution:** Use `description_lines_count=1` or `=2` to force fewer
lines, or rewrite the repo description to fit.

---

## 7. FAQ

**Q: Do I need to deploy my own instance?**

For low-traffic profiles, no — the public `github-readme-stats.vercel.app`
instance is fine. For high-traffic READMEs (popular profiles, project
pages, organisations), self-hosting is recommended. Issue #1406 (47
comments) and the recurring "DEPLOYMENT_PAUSED" reports are direct
evidence that the public instance is sometimes saturated.

**Q: Why does my star count not match my profile?**

By default the stats card sums stars across the first 100 repos returned
by GitHub's GraphQL (sorted by stars descending). If you have more than
100 repos the long tail isn't included. Set the env var
`FETCH_MULTI_PAGE_STARS=true` on your self-hosted instance to fetch every
page; the public instance keeps it off to manage rate-limit budget.

**Q: Are private commits counted?**

Last-year commit count uses
`contributionsCollection.totalCommitContributions`, which includes
private contributions only if the user has enabled "Include private
contributions on my profile" on github.com. Issue #4837 tracked this
behaviour. `include_all_commits=true` uses the public search-commits
endpoint and excludes private repos entirely.

**Q: Why are my colors ignored?**

Color parameters expect hex codes WITHOUT the leading `#`.
`title_color=ff79c6` works; `title_color=#ff79c6` does not. Invalid hex
values silently fall back to the theme color, then to the `default`
theme.

**Q: Can I use this on GitLab/Hashnode/Dev.to?**

Yes — anywhere that renders Markdown image syntax or HTML `<img>` tags
will display the cards. The hosted instance returns standard SVG with
permissive cache headers.

**Q: How do I know if the public instance is down?**

Hit `https://github-readme-stats.vercel.app/api/status/up`. It returns a
JSON boolean (or a Shields.io-compatible response with `?type=shields`).
The `pat-info` endpoint returns valid/exhausted/expired/error status for
each PAT in the running instance.

**Q: How do I count reviews instead of issues?**

Add `show=reviews` and (optionally) `hide=issues`. The five optional
`show=` keys are `prs_merged`, `prs_merged_percentage`, `reviews`,
`discussions_started`, `discussions_answered`. `stars`, `commits`,
`prs`, `issues`, and `contribs` are always on unless you `hide=` them.

**Q: Can I use this offline / behind a corporate proxy?**

Self-host the Express adapter (`node express.js`) and point your README
at your internal URL. The only outbound dependencies are
`api.github.com` (GraphQL + REST) and `wakatime.com` (or your custom
`api_domain`).

**Q: How do I get the rank S?**

S is reserved for the top tier by the rank algorithm. Roughly: very high
star count, lots of merged PRs, sizable follower count, and a steady
review history. The exact thresholds are computed from CDFs of the
medians (50 stars, 50 PRs, 250 commits/year, 25 issues, 2 reviews,
10 followers); see the rank algorithm note in section 4.1 if you want to
poke at the math yourself.

**Q: Can I add a theme?**

Yes — open a PR adding a new entry to `themes/index.js`. The repo has
helper scripts (`scripts/preview-theme.js`,
`scripts/generate-theme-doc.js`) and a stale-theme-PR closer that
automate the housekeeping. Themes must declare `title_color`,
`icon_color`, `text_color`, `bg_color`, optionally `border_color`. Hex
without `#`.

**Q: What's the maximum description length on the pin card?**

The repo description wraps at 59 characters per line and tops out at 3
lines (the limit you can clamp with `description_lines_count=`). Beyond
that, the renderer adds `...` to the last line.

**Q: Why does my WakaTime card show a different card when nothing changed?**

The WakaTime card has three "no data" states it cycles through:
profile-not-public, code-stats-hidden, and zero-activity-this-week. If
your settings shift on the WakaTime side mid-week, the card text shifts
to match.

---

_Generated April 2026 from anuraghazra/github-readme-stats at 5df91f9. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._