Guide

Missing icons

Raise loudly in development, degrade gracefully in production.

The policy#

Configured once, in an initializer.

config/initializers/glyphs.rb

Glyphs.configure do |config|
  # Re-raise Icons::IconNotFound? Defaults to true in local Rails
  # environments (and outside Rails), false otherwise.
  config.raise_on_missing = Rails.env.local?

  # Rendered instead of the missing icon (per library).
  # A library without an entry re-raises.
  config.fallback_icons = {
    lucide: "circle-question-mark",
    phosphor: "question",
    heroicons: "question-mark-circle"
  }
end

With raise_on_missing true a typo fails fast in development and test. With it false (production), the library's fallback icon renders instead so the page never 500s over a missing glyph. If the fallback itself is missing, the original error re-raises — no silent loops.

The instrumentation hook#

on_missing_icon is an optional handler, called before the fallback renders (never when raising). Wire it to your logger or error tracker:

config/initializers/glyphs.rb

Glyphs.configure do |config|
  config.on_missing_icon = lambda do |error, name:, library:, variant:|
    Rails.logger.error(
      "Icon missing: #{library}/#{variant}/#{name} (#{error.message})"
    )
  end
end

Interaction with the SVG cache#

Fallback renders are cached under the original icon name, so on_missing_icon fires once per process per missing icon, not on every render — your logs stay readable while the fallback keeps rendering. Set config.cache_svgs = false to trade that for a notification per render.