Troubleshooting

🩹 Troubleshooting

Errors are written to stderr and mapped to a stable exit code: 2 means you can fix it in your config or flags, 1 means something went wrong at run time.

---

no config found

no config found; pass --config, set NERD_FONTS_INSTALLER_CONFIG, or create one of: …

The message lists every path that was searched, computed live for your machine. Three ways forward:

# 1. create one
mkdir -p ~/.config/nerd-fonts-installer
$EDITOR ~/.config/nerd-fonts-installer/config.yaml

# 2. point at one
nerd-fonts-installer --config /path/to/fonts.yaml

# 3. skip the file entirely
nerd-fonts-installer --interactive

See ⚙️ Configuration for the full discovery order.

---

no config found; --interactive requires stdin and stdout terminals

You passed --interactive from a pipe, a CI job, or a cron run. A TUI has nothing to attach to there. Use a config file instead:

NERD_FONTS_INSTALLER_CONFIG=/etc/fonts.yaml nerd-fonts-installer

---

nerd fonts release "v9.9.9" was not found

The release value does not match any release tag. Check the spelling — tags include the leading v (v3.4.0, not 3.4.0). To see what exists, use latest once and read the header line of --font-names:

nerd-fonts-installer --font-names | head -1

---

duplicate font family "Hack"

The same name appears twice under families:. Remove one. Comparison is on the trimmed name, so Hack and Hack count as the same family.

---

unsafe font family name "…"

A family name contained a path separator, .., a leading -, or another character that must never reach a filesystem path or a URL. This is a deliberate guard, not a bug. Family names are plain archive names:

families:
  - JetBrainsMono   # ✅
  - ../../etc       # ❌ rejected

---

download … 404 Not Found

Nearly always a wrong family name or release tag — a family that exists in v3.4.0 may not exist in v3.1.0.

nerd-fonts-installer --font-names

Copy the exact name from that output. Note the archive name is JetBrainsMono, while the installed font is called JetBrainsMono Nerd Font — you use the first in your config and select the second in your terminal.

---

checksum mismatch for X: downloaded sha256 …, expected …

The downloaded archive did not match the digest in the release's SHA-256.txt manifest, and the install was aborted before anything was written. Usually a truncated or proxy-mangled download — just re-run. If it repeats, check whether a corporate proxy or transparent cache is rewriting the response.

A missing manifest is different: you get a warning (Checksum manifest unavailable …) and the install continues. A mismatch is always fatal.

---

exceeds N byte limit

Guards against zip bombs and pathological archives:

Limit	Value	Applies to
Download size	768 MiB	One downloaded .zip
Font file size	128 MiB	One extracted .ttf/.otf/.ttc
Archive total	2 GiB	Total uncompressed bytes per archive

Real Nerd Font archives are nowhere near these. Hitting one means the URL is not serving what you expect.

---

extract …: no font files found

The archive downloaded and opened, but contained no .ttf, .otf, or .ttc. Check that the family name refers to a font archive rather than a source or documentation asset in the release.

---

run fc-cache for …

fc-cache was found but exited non-zero. The fonts are already installed at this point — only the cache refresh failed. Run it yourself to see the real error:

fc-cache -f -v ~/.local/share/fonts/NerdFonts

If fc-cache is simply not installed, that is not an error: you get fc-cache is not available; skipping font cache refresh. and the run succeeds. Install fontconfig if you want the refresh.

---

The font installed but nothing shows it

Three things to check, in order:

1. Refresh the cache

   fc-cache -f ~/.local/share/fonts/NerdFonts
   fc-list | grep -i "nerd font" | head

2. Restart the application. Terminals and editors read the font list at startup. GNOME, KDE, and macOS may need a logout for every app to notice.

3. Select the patched name. Installing is only half the job:

   JetBrainsMono Nerd Font
   Hack Nerd Font Mono
   FiraCode Nerd Font Propo
   

   Mono variants force single-width glyphs (best for terminals); Propo uses proportional icon widths (better in editors and UI).

---

Icons are still boxes or question marks

The font is not actually selected, or the app overrides it. In VS Code, remember terminal.integrated.fontFamily is separate from editor.fontFamily. In tmux, the outer terminal's font is what matters.

For the picker itself, drop to a simpler icon set:

nerd-fonts-installer --interactive --icons ascii

---

Permission denied writing fonts

The destination is not writable by your user. Prefer a per-user directory:

destination: ~/.local/share/fonts/NerdFonts

Installing system-wide (/usr/share/fonts/...) needs elevated privileges and is generally not what you want for a personal font set.

---

Rate limited by GitHub

--font-names and the picker call the public GitHub API, which allows 60 unauthenticated requests per hour per IP. On a shared or NAT'd network you can hit that. Wait for the window to reset, or pin release: in your config so a plain install does not need to list releases.

---

Still stuck?

Run with --dry-run first — it shows exactly which URLs and paths the tool resolved — and include that output plus nerd-fonts-installer --version when you open an issue.

---

Next: ❓ FAQ · 🏗️ Architecture