Awesemo for Craft CMS

Troubleshooting

Start here

php craft awesemo/health/check

Or open Awesemo → Health. It covers the failures that are silent by design — an icon that does not exist renders as nothing, which looks like a spacing bug rather than a missing icon. Almost everything below is something that screen already says out loud.

Every icon on the site is a blank square

The stylesheet is not on the page. In order of likelihood:

  1. Delivery is off and the mode is web font. Web-font icons need the stylesheet. Set delivery to automatic, or switch to inline SVG, which needs none. The health screen calls this an error, not a warning.
  2. Delivery is manual and no template calls {{ craft.awesemo.head() }}.
  3. The source is "loaded by the site itself" and the site is not loading it.
  4. The stylesheet URL does not answer. A pinned version that does not exist, or a self-hosted path served from a URL that 404s. The health screen fetches it and tells you.

One icon is missing, the rest are fine

The name does not resolve. Check it the way a template would:

php craft awesemo/catalog/search thumbs

Usual causes:

  • A typo. fa-user-cirlce.
  • A Pro icon on a free source. It exists in Font Awesome, not in the free package.
  • A style the icon does not come in. regular:user is real; regular:house is not.
  • A name Font Awesome retired, with legacy resolution turned off.
  • A catalogue built before that icon existed. Rebuild it.

To find every one of them at once, across templates and element content:

php craft awesemo/icons/usage

The Usage screen then shows each unknown name and every template and entry it is written in.

Icons went blank after another plugin was installed

Two copies of Font Awesome on one page. Whichever stylesheet loads last owns the class names, and everything from the other version goes blank — this is the single most common way icons break in a CMS, and it is why the plugin exists.

Turn on Remove duplicate Font Awesome in settings. Awesemo then strips Font Awesome stylesheets and kit scripts that something else put on the page, and never its own. The health screen also lists the templates the other tag is written in, so you can delete it properly.

If the other copy is the one you want, set Awesemo's source to Loaded by the site itself instead.

SVG mode is doing nothing

Icons render as web font even though the mode is set to SVG. That means the catalogue has no path data — it was built from a stylesheet rather than from metadata, which is what happens with a kit or a self-hosted package without a metadata/ directory.

A stylesheet lists names and code points and nothing else. There is no path data in it to find. Point the source at a package with metadata/ (the CDN source always has one) and rebuild, or stay on web font. The fallback is deliberate: SVG and sprite modes fall back rather than rendering nothing.

The sprite 404s

Sprite mode points every icon at /awesemo/sprite.svg, which does not exist until it is built:

php craft awesemo/icons/usage
php craft awesemo/icons/sprite

In that order — the sprite is built from what the scan found. Also check the sprite route setting is on.

Nothing can be searched and the picker is empty

No catalogue has been built for the current source.

php craft awesemo/catalog/build

Remember that <key> hashes the source configuration: changing the version, the provider or the kit points at a different catalogue, which may not have been built yet. Changing back is instant, because the old one is still on disk.

Icons disappeared after a deploy

storage/ was wiped. Everything in storage/awesemo/ is derived data, and one download restores it:

php craft awesemo/catalog/build
php craft awesemo/icons/usage
php craft awesemo/icons/sprite

Put those in the deploy script, followed by awesemo/health/check.

The version in settings is not the version on the page

Expected, if the version is a range. 6 lets the CDN serve the newest release in that line. The catalogue records the concrete version it resolved to:

php craft awesemo/catalog/info

or {{ craft.awesemo.version() }}. Pin an exact version if staging and production must not drift — and pin it in config/awesemo.php rather than the control panel, so it cannot be changed by hand on one environment.

The editor button does nothing

  • CKEditor: the button is disabled while the selection is a block widget — an image, a table. That is correct, and indistinguishable from a broken button. Put the caret in a paragraph.
  • Redactor: if an icon is inserted but comes back as <em> with no classes, that is Redactor's own tag rewriting plus HTML Purifier. Awesemo inserts a <span> for exactly this reason; content written by an older version is upgraded by |awesemoIcons, which handles <i>, <span> and <em>.
  • Neither button appears: the integrations activate only when those plugins are installed. Clear caches after installing one: php craft clear-caches/cp-resources.

An author's icon is fine in the control panel and missing on the front end

Almost always a CSS subset. If CSS files is a subset like fontawesome, solid, brands and the author picked a regular icon, the class is right and the font is not loaded. The health screen compares the subset against the styles the site's content actually uses and names the gap.

Everything else

Turn on Warn on unknown icons (on by default) and read the Craft logs — every name that failed to resolve is in there with the template that asked for it.

If a page is broken in a way none of this explains, the deliberate design rule is worth remembering: an unknown icon costs an icon, never the page. If a page is failing rather than an icon, it is probably not Awesemo.

Next