If your Dashy icons are not working, the problem is often easier to fix than it looks. A wrong icon name, a missing icon pack, a broken favicon source, or a local file path can all cause icons to disappear.
I would start with the simple checks first. You usually do not need to rebuild your whole Dashy setup. Dashy supports several icon types, including Font Awesome, Simple Icons, Material Design Icons, favicons, local images, emoji, and other icon packs. That means the right fix depends on the icon type you are using.
Why Are Dashy Icons Not Working?
Dashy icons can stop showing for several reasons.
The most common ones are:
- The icon name is wrong.
- The icon prefix is missing.
- The selected icon pack is not loading.
- Font Awesome is not enabled.
- A favicon service cannot fetch the icon.
- A local icon path is wrong.
- The image URL is not reachable.
- Your browser has an old cached version.
- A custom icon file is in the wrong folder.
- The icon is not available in the supported icon version.
The first thing I would do is identify which type of icon is failing. That can quickly narrow down the problem.
Check Your Icon Name First
This is the easiest place to start.
Dashy uses specific names for its icon providers. You cannot always type the name of an icon as it appears on an icon website and expect it to work.
For example, a Material Design Icon needs the correct mdi- prefix. A Font Awesome icon needs the proper category and icon name.
A small spelling mistake can be enough to show a blank or broken icon.
I would copy the icon name carefully and compare it with the format supported by Dashy.
Check the Icon Prefix
If you are using an icon pack, the prefix matters.
For Material Design Icons, the icon uses the mdi- prefix. So an icon may look like:
icon: mdi-fireFont Awesome uses a different format.
For example:
icon: fas fa-serverThe first part tells Dashy which Font Awesome style to use. The second part identifies the icon.
If you use the wrong prefix, Dashy may not know which icon you want.
Dashy Font Awesome Icons Not Working
Font Awesome is one of the more common causes of icon problems.
Dashy can normally enable Font Awesome when it sees that you are using a Font Awesome icon. If that does not happen, you can enable it in your configuration.
The setting is:
appConfig:
enableFontAwesome: trueThen check your icon format.
A Font Awesome icon should use a supported category such as:
icon: fas fa-databaseor:
icon: fab fa-raspberry-piThe exact icon name also matters.
If you copied an icon name from a newer Font Awesome collection, check that the icon is supported by the version used by your Dashy setup. A newer icon may not work simply because it exists on the current Font Awesome website.
Check Your Font Awesome Icon Category
Font Awesome has different icon styles.
Dashy supports categories such as:
farfor regularfasfor solidfalfor lightfadfor duotonefabfor brands
For many normal icons, fas is the easiest option to try.
For example:
icon: fas fa-homeFor a brand icon, you would normally use the brand category.
If the category and icon name do not match, the icon may not appear.
Are Only Some Icons Missing?
This is an important clue.
If most of your Dashy icons work but one or two do not, I would suspect the icon name first.
Try replacing the broken icon with a simple icon that you know exists.
For example:
icon: mdi-homeIf that works, your Dashy installation is probably fine. The original icon name or icon provider is more likely the problem.
This is a much better test than changing several settings at once.
Check Favicon Icons
Dashy can also use website favicons.
A favicon setup may look like:
icon: faviconDashy can use favicon services to find an icon for a website. Different services may work better for different sites.
If a favicon does not load, the problem may not be Dashy itself. The website may not expose its favicon in a way the selected service can find.
In that case, I would try another favicon method or use a direct image instead.
Try a Direct Image URL
If a favicon keeps failing, a direct image URL can be a useful test.
For example:
icon: https://example.com/icon.pngThe image needs to be reachable from the device or server running Dashy.
This method can help you tell whether the problem is with the icon provider or with Dashy itself.
If the direct image works but the favicon does not, the favicon lookup is likely the part that needs attention.
Check Local Icons
Local icons are useful when you do not want to depend on an outside icon service.
Dashy supports local icons inside its user-data area. A common location is:
user-data/item-icons/For example, if you have:
user-data/item-icons/myapp.pngyou can reference it with:
icon: myapp.pngYou can also organize icons into folders.
For example:
user-data/item-icons/networking/monitor.pngThen the icon can be referenced with the folder path.
If a local icon does not appear, I would check the filename, extension, folder, and spelling first.
Check Docker Volume Mapping
This one matters if you run Dashy in Docker.
Your local icon may exist on your computer but still be invisible to the Dashy container.
The container needs access to the folder where the icon is stored.
If the user-data directory is not mounted correctly, Dashy may not see your custom files.
I would check the Docker volume before changing the icon configuration itself.
This is especially useful when built-in icons work but your own PNG or SVG files do not.
Clear Your Browser Cache
Sometimes the configuration is correct, but the browser is still showing an older version.
I have seen this happen with web dashboards after configuration changes.
Try a hard refresh.
You can also open Dashy in a private browser window. If the icons work there, cached files may be the reason.
Do not immediately rebuild Dashy just because one browser shows an old icon.
A fresh browser test can save a lot of time.
Check the Browser Console
If the easy fixes do not work, the browser console can tell you much more.
Open your browser’s developer tools and check the Console and Network tabs.
Look for errors related to:
- Fonts
- Images
- SVG files
- Failed requests
- 404 errors
- Blocked resources
- CORS errors
This is especially useful for icons loaded from URLs.
If the browser cannot reach the icon file, changing the YAML syntax will not solve the underlying connection problem.
Check Whether the Icon Provider Is Reachable
External icons need to be reachable from the environment where Dashy runs.
This matters more on private networks.
For example, an icon URL may work on your laptop but fail from a Docker container or another device.
The same can happen with favicon services.
If the icon depends on an outside service, test whether that service can actually be reached from your Dashy environment.
Try a Built-In Icon as a Test
This is one of my favorite troubleshooting steps because it is simple.
Replace your current icon with a basic built-in icon.
For example:
icon: mdi-homeThen reload Dashy.
If it appears, your main Dashy interface is probably loading icons correctly.
Now change only the icon value back to the one that was failing.
If the problem returns, you have narrowed the issue down to that specific icon.
Dashy Icons Not Working: Quick Troubleshooting Table
| Problem | What I Would Check |
|---|---|
| All icons are missing | Icon assets, browser cache, and Dashy configuration |
| One icon is missing | Icon name and spelling |
| Font Awesome icons fail | Font Awesome setting and icon format |
| Favicon fails | Favicon provider or website favicon |
| Local icon fails | File name and item-icons path |
| URL icon fails | Image URL and network access |
| Docker icon fails | Volume mapping |
| Icon appears after refresh | Browser cache |
| New icon does not work | Icon version and supported name |
| Built-in icon works | Original icon configuration |
Check Your Dashy Configuration
Dashy stores its main configuration in the user-data area.
The configuration can be edited through the YAML file or through the Dashy interface.
If you recently changed several icon settings, I would check the configuration carefully.
YAML is sensitive to formatting. A small indentation problem can affect how the configuration is read.
Keep the icon value simple while testing.
For example:
items:
- title: Home
icon: mdi-homeOnce that works, you can move back to your more complex icon setup.
What If Dashy Shows a Broken Default Icon?
A broken or generic icon can mean Dashy could not fetch the requested image.
This is common with external icons.
If you are using a homelab icon, favicon, or remote image, try a simple built-in icon first.
If the built-in icon works, the problem is likely with the external icon source or name.
I would not change the whole Dashy theme just to fix one missing icon.
When Should You Update Dashy?
If you are running an older Dashy version, an update may help with bugs that have already been fixed.
But I would not update immediately.
First, test a basic icon. Check the configuration. Check the browser console. Then look at the version you are running.
If the issue started after an update, the version change itself is also worth considering.
Keep a backup of your configuration before making a major change.
When the Problem Is Not Really an Icon Problem
Sometimes the icon is fine, but another part of the page is causing the visual problem.
Custom CSS can change how icons look.
For example, CSS may affect:
- Icon size
- Opacity
- Display
- Font family
- Color
- Spacing
- Visibility
If you recently added custom CSS, temporarily disable it.
Then check the icon again.
If the icon comes back, the CSS is likely hiding or changing it.
My Simple Fix Order for Dashy Icons
When Dashy icons stop working, I would not change everything at once.
I would use this order:
- Test a simple built-in icon.
- Check the icon name.
- Check the icon prefix.
- Check the icon pack.
- Check Font Awesome settings if needed.
- Test a direct image URL.
- Check local icon paths.
- Check Docker volume mapping.
- Hard-refresh the browser.
- Check the browser console.
- Review recent configuration changes.
- Consider updating Dashy if the issue points to an older version.
This gives you a clean way to find the cause without creating new problems.
FAQs
Why are my Dashy icons not working?
Start with the icon name and prefix. Then test a simple built-in icon to see if the problem affects all icons or only one type.
Why are Font Awesome icons not showing in Dashy?
Check that Font Awesome is enabled and that the icon uses the correct category and name. Also check whether the icon is supported by the Font Awesome version used by your Dashy setup.
Why is my Dashy favicon not loading?
The favicon provider may not be able to find the site’s icon. Try another favicon method or use a direct image instead.
Why do local Dashy icons not work?
Check that the image is inside the correct user-data/item-icons folder and that the file name and extension match your configuration. Docker users should also check their volume mapping.
Why does a Dashy icon work on one device but not another?
The second device may not be able to reach the icon source. This can happen with local files, private URLs, network paths, or external icon services.
Conclusion
If your Dashy icons are not working, start small. Test a basic icon first, then check the name, prefix, icon provider, and configuration.
For local icons, check the file path and Docker volume. For remote icons, check the URL and network access. For Font Awesome, check the category and icon version.
The key is to change one thing at a time. That makes it much easier to find the real cause without breaking a Dashy setup that is otherwise working well.