Troubleshooting

“Pack not found”

Check the full three-part identifier:

org / project / pack

All three segments are required and need to match the current slugs. Slugs are auto-generated from names — if the org was renamed, the old slug stops working.

”No published releases”

The pack exists but hasn’t been published yet. The author needs to publish at least one release from the app before it can be installed.

Old install paths stopped working after a rename

That’s expected. Slugs are derived from names, and there’s no alias system — when a name changes, the old install path stops working immediately. Developers need to update their install commands and rerun install.

Avoid renaming orgs, projects, or packs once they’re in active use.

CLI picked up a parent project’s config

The CLI uses the nearest package.json to find the project root. If you run it in a subdirectory that doesn’t have its own package.json, it’ll use the parent’s iconforge.json.

Fix: give the subdirectory its own package.json if it should be treated as a separate project.

”Framework mismatch”

The project already has iconforge.json with one framework set, and you tried to install with a different one. All packs in a project share the same framework.

Fix: edit iconforge.json to the intended framework and reinstall, or use a separate project root for a different framework.

Conflicting files at the destination

The CLI distinguishes between files it owns (tracked in the lockfile from a previous install) and unrelated files that happen to be in the way.

For unrelated conflicts:

• --force to overwrite them
• --skip to install only non-conflicting files
• Or move your Icon Forge output to a different directory

”Reinstalling…” messages

Normal. The CLI does a deterministic reinstall — it replaces tracked files even if the version hasn’t changed. A message like “Reinstalling acme/brand/core-icons (42 files)” just means it’s refreshing files it already owns.

Invalid version in config

Pack entries in iconforge.json must be either latest or hash:<12-character-hex>. If you hand-edit a pack entry to something else, the CLI will fail and tell you to fix it.

Local dev / staging

Point the CLI at a different API for local development:

npx @icon-forge/cli install acme/brand/core-icons --api-url http://127.0.0.1:7000

Or via environment variable:

ICONFORGE_API_URL=http://127.0.0.1:7000 npx @icon-forge/cli install acme/brand/core-icons

The API URL isn’t saved to config.