Skip to content
starlight-plugin-icons

Troubleshooting

Missing icons

Section titled “Missing icons”
  • Verify the icon collections are installed.
  • Ensure UnoCSS is installed with the correct presets. It’s recommended to also use presetWind3()
  • Verify that icons have non-zero width and height or font-size.
  • Check that you are using the correct icon class syntax: i-{collection}:{icon}.

Safelist not applied

Section titled “Safelist not applied”
  • Check .starlight-icons/safelist.json exists after dev/build and contains the correct icons.
  • Set SPI_SAFELIST_PATH to a custom safelist if your content folder is nonstandard.

Network fetch errors

Section titled “Network fetch errors”
  • The plugin downloads Material Icons metadata on first run.
Section titled “Sidebar icons not working on Cloudflare”

I’m not sure what the issue is, but Cloudflare Workers don’t load the newly generated safelist during deployment build.

The fix is to commit the safelist to the repo:

.gitignore
.starlight-icons/*
!.starlight-icons/safelist.json