The Nerd Font error in Windows Terminal on Windows 11 occurs when the terminal cannot locate the specified font file, usually due to incorrect installation or a mismatched profile setting. This guide resolves the issue by verifying font installation via the system settings and correcting the
fontFace property in your terminal's JSON configuration to ensure proper rendering of icons and symbols.
Understanding the Error Cause
Windows Terminal relies on specific font files to render glyphs, particularly those used by tools like Powerline, Git status indicators, and custom prompt themes. When you see an error message stating that a Nerd Font is not found, it means the application is looking for a font family name that does not exist in the system's registered fonts or is misspelled in the configuration. This is a common issue after installing new themes or switching between different terminal profiles. The error prevents the terminal from displaying special characters correctly, often resulting in squares, question marks, or blank spaces instead of the intended icons.
Verifying Font Installation
Before modifying any configuration files, you must ensure that the Nerd Font is properly installed and recognized by Windows 11. The most reliable way to check this is through the System Settings app. Open the Start menu and navigate to
Settings > Personalization > Fonts. In the search bar within the Fonts page, type the exact name of the font you are trying to use, such as "CaskaydiaCove Nerd Font" or "JetBrainsMono Nerd Font". If the font appears in the list with its full details, it is successfully installed. If it does not appear, you need to reinstall the font. Download the latest version of your desired Nerd Font from the official GitHub repository, unzip the archive, and right-click the
.ttf or
.otf files to select
Install. After installation, restart Windows Terminal to allow it to refresh its font cache.
Updating the Configuration File
Once the font is confirmed to be installed, the next step is to align your Windows Terminal configuration with the actual font name. Access the settings by clicking the dropdown arrow in the title bar and selecting
Settings, or by pressing
Ctrl + ,. Navigate to the
Profiles section and select the profile that is experiencing the error, such as PowerShell or Command Prompt. Look for the
fontFace field under the appearance settings. This value must exactly match the Family Name of the installed font, which you can verify in the Fonts settings panel. For example, if you installed "Cascadia Code PL", the
fontFace should be set to "Cascadia Code PL". Save the changes and close the settings window. Restart the terminal to apply the new configuration.
Using JSON for Advanced Editing
For users who prefer direct editing or need to apply changes across multiple profiles, you can edit the
settings.json file directly. Click the dropdown arrow in the title bar and select
Open JSON File. Locate the profile object and update the
fontFace key. Ensure there are no trailing spaces or typos. The structure should look like this:
{
"guid": "{...}",
"name": "PowerShell",
"fontFace": "CaskaydiaCove Nerd Font",
"fontSize": 12
}
After saving the JSON file, restart Windows Terminal. If the error persists, verify that the font name in the JSON matches the Family Name exactly, including capitalization.
Clearing the Font Cache
In rare cases, Windows may cache outdated font information, causing the terminal to fail even after correct installation and configuration. To resolve this, clear the font cache by restarting the
FontCache service. Open Task Manager (
Ctrl + Shift + Esc), find
Windows Explorer, and restart it. Alternatively, reboot your computer to ensure all services reload the updated font registry. This step is particularly useful if you recently uninstalled and reinstalled a font.
Checking for Conflicting Profiles
If you have multiple profiles configured, ensure that each one has a valid
fontFace setting. A missing or invalid font face in any active profile can cause errors when switching tabs. Review all your profiles in the settings interface to confirm consistency. Additionally, consider using a standard monospaced font as a fallback if Nerd Fonts continue to cause issues, though this will result in the loss of icon support.
Frequently Asked Questions
Why do I see squares instead of icons?
This indicates that the font lacks the necessary glyphs for the symbols being displayed. Ensure you are using a complete Nerd Font variant and not a stripped-down version. Verify that the
fontFace setting matches the installed font family name exactly.
Can I use any font with Windows Terminal?
Yes, but Nerd Fonts are required for special characters and icons. Standard fonts will work for text but will display replacement characters for powerline symbols. Choose a font specifically labeled as a Nerd Font for full compatibility.
How do I find the exact font family name?
Open Windows Settings, go to Personalization > Fonts, and click on the installed font. The Family Name is displayed prominently at the top. Use this exact string in your
fontFace configuration to avoid mismatches.
What if the error persists after reinstalling the font?
Try clearing the Windows font cache by restarting the computer or restarting the Windows Explorer process. You can also try creating a new profile with a different font to isolate whether the issue is profile-specific or system-wide.
Is there a way to test if the font is working?
Open a new terminal tab and type a command that uses icons, such as
dir in a PowerShell profile configured with Nerd Fonts. If the icons render correctly, the font is working. If not, double-check the
fontFace spelling and installation status.