Troubleshooting

Blank icons, missing names, wrong colours, CORS and npm token problems, and how to fix them.

as Markdown, for notes or an AI chat

The problems people run into most, with the cause and the fix. Each heading links to itself, so you can share an answer.

Icons show as blank or solid squares#

The page is opened from disk. Browsers do not load CSS mask images on file:// pages. Serve the folder with any local server, for example npx serve.
The svg/ folder moved. The stylesheet loads icons from ../svg/ relative to itself. Keep css/ and svg/ side by side.
The stylesheet is linked from hubtoolify.com. Our own server does not allow other sites to use its files as masks. Use the jsDelivr CDN or your own copy of the kit.
A Content Security Policy blocks images. Allow cdn.jsdelivr.net (or your own domain) in img-src; CSS masks count as images.

An icon name does nothing#

Check the spelling against the icon's page address: /icons/shopping-cart is hti-shopping-cart.
A newly drawn icon reaches npm and the CDN with the next release. Until then, download it from its page.
A Pro style class such as hti-slab needs the Pro kit's stylesheet, not the free one. From 2.0.0 that includes hti-solid and hti-duotone.

The colour does not change#

It is an <img>. An image keeps the colour it was drawn in. Use the CSS classes or inline the SVG to colour it with CSS.
A bracket class like hti-text-[#ffffff] does nothing. Bracket values need the helper script; see the CDN page.
Jass, Lineal and 3D have a fixed palette by design; they are not recolourable.

Duotone looks like Line#

The tone defaults to 20% of the icon's colour, which can be faint on a light background. Raise it with --hti-secondary-opacity or hti-tone-40, or give it its own colour with --hti-secondary. Also check you are using a whole Duotone file: hubtoolify.com keeps Duotone only as two layers, so whole files come from jsDelivr or the kit.

React: “is not exported” or a missing icon#

Component names are Hti plus PascalCase: arrow-up-right is HtiArrowUpRight.
Update the package: npm install @hubtoolify/icons-react@latest. Icons drawn after your installed version are not in it.
If your AI agent wrote the import, connect it to the MCP server so it checks names against the published package.

npm: 401 or 403 from the Pro registry#

Your token expired (they last 365 days) or was revoked by a password change. Run npx @hubtoolify/icons login again.
Your Pro plan has ended. Renew it on the pricing page; projects already built keep working.
The scope line is missing from .npmrc. See Pro packages.

Figma: the Solid icon is a mask group#

That is expected: the cut-outs in Solid icons are masks. Select the group and use Flatten if you need a single shape.

WordPress: Pro styles ask me to connect again#

Connections are per WordPress user and follow your current plan. Choose Connect HubToolify account in the block and enter the new code at hubtoolify.com/connect. If your plan ended, the free Line style keeps working and inserted icons stay in your posts.

Something else#

Check system status to see whether a service is having trouble, then contact us with the page address, what you expected and what happened.