Astro Icons Not Showing After Adding a Custom One

I added a custom Telegram icon to my Astro project and immediately broke all the icons on the page — including ones that had been working fine for weeks.

The error was not subtle:

1
Unable to locate "telegram" icon!
2
The icon named "telegram" was not found in your local icon directory.
3
Did you forget to configure your icon directory or make a typo?

1
// Check if the icon is missing from the local collection
2
if (!(iconName in icons[setName].icons)) {
3
  const err = new AstroIconError(`Unable to locate "${name}" icon!`);
4
  if (import.meta.env.DEV) {
5
    err.hint = `The icon named "${iconName}" was not found in your local icon directory.\n\nDid you forget to configure your icon directory or make a typo?`;
6
  }
7
  throw err;
8
}

Except the icon file was right there. In the right folder. Named correctly.

What Was Happening

The setup was straightforward: I dropped a telegram.svg into my local icon directory, referenced it the same way as every other icon, and opened the browser.

Instead of seeing the new icon, I got:

• The Telegram icon missing
• Other previously working icons also gone
• The error message above appearing periodically
• Everything still looking fine in the file system

The weirdest part was that only one icon — the email one — still rendered. The rest had silently disappeared.

The Obvious Suspects

My first instinct was to check the usual things:

• File name: correct
• File path: correct
• Icon directory config in astro.config.mjs: correct
• SVG syntax: valid

Everything looked right. I restarted the development server. Still broken. Restarted again. Same error.

At this point it looked like an Astro bug, or some misconfiguration I was missing. But nothing in the config had changed.

The Real Cause

Astro caches a lot of things internally in a .astro folder at the project root. This cache is used to speed up builds and dev server restarts.

When I added the new icon, something in that cache became stale or inconsistent. The dev server was partially reading from cache, partially from disk, and the two were out of sync. That explained why one icon still worked and others did not — it depended on what was cached and what was not.

Restarting the dev server does not clear this cache. It just reuses it.

The Fix

Delete the .astro folder manually:

1
rm -rf .astro

Then restart the dev server. Astro rebuilds the cache from scratch, picks up the new icon, and everything works.

In my case:

• Telegram icon appeared
• All other icons came back
• No more error messages

No config changes. No reinstall. Just a stale cache.

When to Try This

If you run into Astro icon issues that do not make sense — icons missing after a change, cryptic “not found” errors for files you know exist, or partial rendering where some icons show and others do not — try clearing the cache before anything else:

1. Stop the dev server
2. Delete the .astro folder in the project root
3. Start the dev server again

This also applies beyond icons. The .astro cache can cause confusing behavior after other types of changes too: content collections, type generation, integrations. When something looks correct on disk but Astro behaves as if it is not there, the cache is a good first suspect.

The .astro folder is safe to delete. It is always regenerated on the next run.

Sometimes the bug is not in your code. Sometimes it is just a folder that needs to go.