# Fastfetch troubleshooting

> Paste your error message into search (/) or scan the list below. Error texts are copied from the 2.71.0 source, so they match what your terminal prints.

Canonical page: https://fastfetch.dev/troubleshooting/ · Checked against fastfetch 2.71.0 · Updated 2026-11-06 · Independent guide, not affiliated with the fastfetch-cli project.

**First, two commands**`fastfetch --version` tells you which release you have (many distributions ship old ones), and `fastfetch --show-errors` prints why a module or logo failed instead of silently skipping it.

## "fastfetch: command not found"

- **Right after `apt install fastfetch` printed `E: Unable to locate package fastfetch`:** the install never happened. Ubuntu 22.04 and 24.04, Linux Mint 21 and 22, and Debian 12 don't have fastfetch in their repositories; we reproduced this in clean containers. Use the PPA or the .deb ([Ubuntu, Debian & Mint guide](/install/ubuntu/)).
- **Installed, but the shell can't find it:** open a new terminal, or run `hash -r`. On Windows, winget says `Path environment variable modified; restart your shell`, so open a new PowerShell window.
- **Every new terminal prints it:** you uninstalled fastfetch but your shell's startup file still runs it. Remove the line ([where to look](/startup/#disable)).

More cases, including Homebrew on Linux and unpacked binaries, are on the [install page](/install/#command-not-found).

## fastfetch prints nothing or stops with an error

1. Check the exit code: `fastfetch; echo $?`. Anything but 0 means it stopped early, and the reason is on stderr.
2. Run once without your config: `fastfetch -c none`. If that works, the problem is in your config file. A config error stops fastfetch with a message such as `JsonConfig Error (display.foo): Unknown display property`. With `--format json` the error still goes to stderr and nothing is printed on stdout, which looks like "no output" in scripts (exit 221 on Linux and macOS, 477 on Windows, in our tests).
3. If it says `unknown option`, the command came from a guide for a different version ([below](#old-commands)).

## Config changes aren't showing up

- **Wrong file name.** fastfetch only loads `config.jsonc` or `config.json5` automatically. A file named `config.json` is ignored (that's in the source: those are the only two names it tries).
- **Wrong folder.** Run `fastfetch --list-config-paths`; the folder holding the config it loads is marked `(*)`. The first match wins, so an older file earlier in the list hides yours.
- **Something passes `-c`.** On Bazzite, `fastfetch` is an alias that loads Bazzite's own config ([fix](/install/#immutable)). Check your own aliases with `type fastfetch`.
- **A key is misspelled inside a module.** Unknown keys inside a module are ignored silently. Run `fastfetch --show-errors` to see `Unknown JSON key` messages, and add the [`$schema` line](/config/#validate) so your editor catches them.

## The logo isn't changing

- **A typo in the logo name** silently falls back to your distribution's logo. With `--show-errors`, `-l not-a-real-logo` printed `Logo: Failed to resolve logo source: not-a-real-logo` in our test. Names are case-insensitive; `fastfetch --list-logos` lists them all.
- **An image file that isn't found** gives the same message. Relative paths are resolved from the current directory, not the config file's folder ([tested](/logos/images/#paths)).
- **An old cached image:** after changing the logo type for the same picture, run once with `--logo-cache regen`.
- **Your config isn't loaded at all:** see [above](#config-not-used).

## "JsonConfig Error" after an upgrade

Recent releases renamed or removed options. Errors in the `logo`, `general` or `display` sections stop fastfetch; module-level notices only appear with `--show-errors`. Find your message below:

| Release | Message you see | Fix | Tested |
| --- | --- | --- | --- |
| 2.71.0 | `Separator: Property 'string' must not be empty` (only with `--show-errors`; otherwise the default `-` is used) | Remove `"string": ""` from the separator module, or give it at least one character. To hide the line, remove the module. Before 2.71.0 the same config made fastfetch hang. | ✓ |
| before 2.71.0 | `Error: unknown --logo-type value: spin` or `JsonConfig Error (logo.type): Invalid enum string` | The [spin logo](/logos/#spin) needs 2.71.0 or newer. Check `fastfetch --version`. | ✓ |
| 2.70.0 | `useStdErr is deprecated, use useOutput instead` | In Command modules, replace `"useStdErr": true` with `"useOutput": "stderr"` (or `"stdout"`; the default is `"both"`). | ✓ |
| 2.70.0 | A `qjs:…` format prints as raw text | QuickJS scripting was removed. Rewrite the script in Lua (`lua:`). | – |
| 2.70.0 | `{size-available}` prints literally in Disk | Use `{size-free}`, which now follows `"useAvailable"`. | – |
| 2.70.0 | `-l postmarketos` shows your normal logo | The logo was renamed: use `-l nura`. | ✓ |
| 2.69.0 | `JsonConfig Error (logo.recache): Property 'logo.recache' has been replaced by 'logo.cache' with the value "regen"` | Delete `"recache"` from `logo`. Use `"cache": "regen"` to force regeneration, or `true`/`false`. | ✓ |
| 2.69.0 | `--logo-recache has been replaced by --logo-cache regen` | Use `--logo-cache regen`. | ✓ |
| 2.67.0 | `Error: unknown option: --gen-config-force` | Removed, along with `--gen-config-full`. Run `fastfetch --gen-config`; the interactive setup asks before overwriting, and its `o` key switches to a full config. | ✓ |
| 2.67.0 | `JsonConfig Error (general.preRun): general.preRun is removed due to security concerns.` | Remove `preRun` from `general`. | ✓ |
| 2.63.0 | `JsonConfig Error (general.wmiTimeout): Unknown general property` | Remove `wmiTimeout` (Windows); it no longer exists. | – |
| 2.58.0 | `` Key `slowVersionDetection` is deprecated, it's always true `` | Remove it from the DE module. | – |
| 2.53.0 | `The option length has been renamed to times.` | In Separator modules, rename `"length"` to `"times"`. | – |
| 2.52.0+ | `Error: Unsupported module option: --cpu-temp` | Per-module flags were removed in 2.50.0. Put the option in the config, e.g. `{"type": "cpu", "temp": true}`. The error message prints the exact JSON to use. | ✓ |
| 2.50.0 | `JsonConfig Error (display.bar): display.bar.charElapsed has been renamed to display.bar.char.elapsed.` | Same pattern for `charTotal` → `char.total`, `borderLeft` → `border.left`, `borderRight` → `border.right`. | ✓ |
| 2.50.0 | `Error: unknown option: --load-config` | Use `-c` / `--config`. | ✓ |
| 2.50.0 | `JsonConfig Error (display.Separator): Unknown display property` | Keys are case-sensitive since 2.50.0: write `separator`. | ✓ |

✓ means we reproduced the exact message by running fastfetch (2.70.0, or 2.71.0 for the 2.71.0 rows) on Linux, macOS and Windows (see the [lab results](/lab/)). – means it is taken from the source code only.

Other messages you may meet:

- `` Error: failed to parse JSON config file `…` at (row, col): … ``: a syntax error (missing comma or quote) at that line and column.
- `Error: couldn't find config: …`: the name passed to `-c` doesn't exist. Presets are listed by `fastfetch --list-presets`.
- `module object must contain a "type" key ( case sensitive )`: a module object without `"type"`.
- `` Error: module `command` is not supported with `--structure` ``: Command modules can't be selected with `-s`; put them in the config.

## No colors, or black-and-white output

Fastfetch turns colors off when its output isn't a terminal (piped, redirected) or when the `NO_COLOR` environment variable is set. The ASCII logo still prints, without colors; image logos are skipped.

- **Powerlevel10k:** its instant prompt captures everything printed after it starts, so the output "may appear uncolored" (Powerlevel10k's docs). Move `fastfetch` above the instant-prompt block in `~/.zshrc` ([example](/startup/#p10k)).
- **Force colors:** `fastfetch --pipe false`.
- **Check for NO\_COLOR:** `echo $NO_COLOR` (any value disables colors).

## Adding fastfetch to .bashrc broke scp, sftp or rsync

Non-interactive SSH sessions also read `~/.bashrc` on Ubuntu and Debian, and any output there corrupts file transfers. In our test, a bare `fastfetch` at the top of `~/.bashrc` made scp fail with `scp: Ensure the remote shell produces no output for non-interactive sessions.` and rsync with `protocol incompatibility (code 2)`. Only run fastfetch in interactive shells ([full test](/startup/#scp)):

*~/.bashrc*

```bash
[[ $- == *i* ]] && fastfetch
```

## Image logo not showing

fastfetch replaces an image it can't draw with your distribution's ASCII logo, silently unless you add `--show-errors`. These are the messages we saw in our tests, with what each means:

| Message | Fix |
| --- | --- |
| `Logo: Failed to resolve logo source: …` | The file wasn't found, or the logo name is misspelled. Use `~/` or an absolute path. |
| `Logo: Failed to load / convert the image source` | The image library is missing: install libchafa for `chafa`, or ImageMagick for `kitty`/`sixel` on Linux. |
| `Logo: getCharacterPixelDimensions() failed` | The output isn't a terminal, or the terminal doesn't report its size. Run fastfetch directly in the terminal. |
| `Logo: Image logo is not supported in pipe mode` | Output is piped or `NO_COLOR` is set (message from the source code). |
| `Logo: the image source can not be animated by this build` | GIF playback needs ImageMagick 7 on Linux; drop `--logo-animation-frame 0`. |

Also make sure the logo type suits your terminal: kitty for kitty, Ghostty and WezTerm; iterm for iTerm2; sixel for Windows Terminal; chafa for everything else. The [image logo guide](/logos/images/) covers every case, with screenshots.

## Icons show as boxes or question marks

You're using icon keys (`display.key.type` set to `icon` or `both`) or `keyIcon` without a Nerd Font in your terminal. Install a font from [nerdfonts.com](https://www.nerdfonts.com/) and select it in your terminal settings, or switch back to text keys (`"type": "string"`).

## GPU shows as "Device XXXX" or a generic name

Your PCI ID database is older than your GPU. The README's fix: download [pci.ids](https://pci-ids.ucw.cz/v2.2/pci.ids) and overwrite `/usr/share/hwdata/pci.ids`. For AMD, also update `/usr/share/libdrm/amdgpu.ids` from Mesa. Or ask the driver directly:

*config.jsonc*

```jsonc
{ "type": "gpu", "driverSpecific": true }
```

The README still shows the old `--gpu-driver-specific` flag; that stopped working in 2.50.0.

On Linux with an AMD GPU whose PCI device or revision ID starts with zeros, versions before 2.71.0 could miss the name in an up-to-date `amdgpu.ids`; 2.71.0 fixes that lookup.

## CPU or GPU temperature is missing

Temperature is off by default. Enable it per module with `{"type": "cpu", "temp": true}` (same for `gpu` and `battery`). If it still doesn't appear, your system doesn't expose a sensor fastfetch can read; `--show-errors` says which.

## Package count is lower than Neofetch's

The README explains that Neofetch over-counted: on Debian-based systems it included removed packages that still have config files (`rc` state), and on RPM systems it counted `gpg-pubkey` entries. On Windows, winget packages are not counted by default; `{"type": "packages", "disabled": []}` enables every package manager.

## Shell shows mise or atuin instead of your shell

Before 2.71.0, the Shell module could report a tool that sits between the terminal and your shell, such as the `mise` version manager or `atuin` shell history, as the shell itself ([#2686](https://github.com/fastfetch-cli/fastfetch/issues/2686)). 2.71.0 skips both. On an older version, update, or use a `"format"` on the shell module that prints the shell you want.

## Memory usage differs from other tools

Tools define "used" memory differently; the project discusses this in [issue #1096](https://github.com/fastfetch-cli/fastfetch/issues/1096). Since 2.65.2, ZFS ARC cache is not counted as used.

## Fastfetch feels slow

Measure first: `fastfetch --stat` appends each module's time in milliseconds (and also turns on error output). Usual suspects:

| Module | Why it takes time | What to do |
| --- | --- | --- |
| CPUUsage | Samples twice, `waitTime` apart (default 200 ms) | Remove it, or lower `waitTime` |
| NetIO, DiskIO, Top | Sample twice (default 250 ms) | Remove, or lower `waitTime` |
| PublicIp, Weather | Network requests | Remove, or set a shorter `timeout` |
| TerminalTheme | Waits up to 1 s for the terminal to answer | Remove it if your terminal doesn't answer color queries |
| Packages | Counts many package databases | Use `"disabled"` to skip managers you don't use |
| OpenGL, Vulkan | Initialize a graphics API | Remove if you don't need them |

#### Total run time of the ci.jsonc preset on upstream CI

Wall-clock time per runner, latest CI run (2026-11-02). Hover a bar for how much is deliberate waiting.

| Runner | Total process time, ci.jsonc preset |
| --- | --- |
| Linux x86-64 | 290 ms |
| Linux ARM64 | 270 ms |
| macOS ARM64 | 800 ms |
| Windows x86-64 | 2590 ms |
| Windows ARM64 | 2490 ms |

Source: [fastfetch CI benchmark](https://fastfetch-cli.github.io/fastfetch/dev/bench/)

The Windows totals are high because CI runners have no real terminal, so terminal queries wait their full timeout. That is not typical of a desktop.

**It never finishes at all?** On 2.70.0 and older, check your config for a separator module with `"string": ""`: in our test that made 2.70.0 hang on Linux, macOS and Windows, and 2.71.0 rejects it instead. Before 2.71.0, fastfetch could also wait forever when the terminal answered a query only partly, for example with only one of the two OSC 10/11 color replies. The changelog lists the logo, Terminal and TerminalTheme code as affected, on Unix and Windows. Update to 2.71.0; on an older version, removing `terminaltheme` from your modules is the first thing to try.

## "Authorization required, but no authorization protocol specified" as root

The README's fix: `export XAUTHORITY=$HOME/.Xauthority` before running fastfetch with root privileges.

## A command from a guide fails with "unknown option"

Either the guide is older than your fastfetch (flags like `--cpu-format` were removed in 2.50.0), or your fastfetch is older than the guide. Debian 13, for example, ships 2.40.4, which lacks `--structure-disabled`, the interactive `--gen-config` and `--logo-cache`. Compare `fastfetch --version` with the [release history](/releases/), and see [which version each distribution ships](/install/#freshness).

## Exit codes in scripts

Fastfetch exits `0` on success. Its error codes are larger than 255, so POSIX shells see them modulo 256 while Windows shows the full number. Test for "non-zero" rather than a specific value:

| Situation | Linux/macOS shell | Windows |
| --- | --- | --- |
| Unknown option | 144 | 400 |
| Config not found (`-c`) | 158 | 414 |
| Config error, or non-interactive `--gen-config` target exists | 221 | 477 |

A module that detects nothing does not change the exit code. [✓ tested](/lab/#checks "Reproduced by running fastfetch 2.70.0 on Linux, macOS and Windows") Every value in this table was measured on Ubuntu, macOS and Windows Server runners.

## Still stuck?

Usage questions go to [GitHub Discussions](https://github.com/fastfetch-cli/fastfetch/discussions), bugs to the [issue tracker](https://github.com/fastfetch-cli/fastfetch/issues). Include the output of `fastfetch --version` and `fastfetch --show-errors`. If something on this page is wrong, email [hello@fastfetch.dev](mailto:hello@fastfetch.dev).

---

Contact: hello@fastfetch.dev · Official project: https://github.com/fastfetch-cli/fastfetch
