Troubleshooting

Most Initium setup issues come from one of five places: shadcn is not initialized, components.json is missing the registry, the license key is unavailable, styles were not installed before blocks, or the AI tool cannot see DESIGN.md and STRATEGY.md.

shadcn Is Not Initialized

Initium installs through shadcn. If your project does not have components.json, initialize shadcn first:

npx shadcn@latest init

After initialization, add the Initium registry to components.json.

The Registry Namespace Is Not Found

If a command like this fails because @initium is unknown:

npx shadcn@latest add @initium/initium-styles

Check that components.json includes the Initium registry:

{
  "registries": {
    "@initium": {
      "url": "https://app.initium.sh/r/styles/{style}/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INITIUM_LICENSE_KEY}"
      }
    }
  }
}

If your file already has a registries object, merge @initium into it instead of replacing other registries.

Free Items Work But Pro Items Return 401

This usually means the registry is configured correctly, but the license key is missing or invalid.

Set the key in your local environment:

INITIUM_LICENSE_KEY=your_polar_license_key

Then retry the pro install:

npx shadcn@latest add @initium/hero-section-1

Do not commit real license keys to your repository.

Installed Components Use Radix Instead Of Base UI

The registry serves two builds and picks one based on the style in your components.json:

• base-* styles (the default for new shadcn projects) receive the current Base UI build.
• radix-* and legacy styles (default, new-york) receive the frozen Radix build, kept for existing customers. It no longer receives new blocks.
• The older style-less URL https://app.initium.sh/r/{name}.json always serves the Radix build, so pre-existing setups keep working unchanged.

If you expected Base UI components but received Radix ones, check that your components.json uses a base-* style and the {style} registry URL shown above. If a block exists for Base UI but the install reports it as missing, your project is likely resolving the frozen Radix build.

Blocks Look Unstyled

Install Initium styles before installing or using blocks:

npx shadcn@latest add @initium/initium-styles

Or install the generated Style Builder preset:

npx shadcn@latest add "https://app.initium.sh/r/preset?code=..."

Also confirm that shadcn is configured to write CSS to the global stylesheet your app actually imports.

The Style Builder Preset URL Fails

Copy the full command from the Style Builder instead of editing the URL manually.

Generated preset URLs look like this:

npx shadcn@latest add "https://app.initium.sh/r/preset?code=..."

Keep the URL quoted. The code value is generated and should not be changed by hand.

AI Tool Ignores DESIGN.md Or STRATEGY.md

Place the files in the project root while you work:

DESIGN.md
STRATEGY.md

Then explicitly ask the tool to read them:

Read DESIGN.md and STRATEGY.md from the project root before editing UI.
Use DESIGN.md for visual direction and STRATEGY.md for page strategy.

If you installed the Initium skill pack, also point the tool at:

.agents/skills/initium/SKILL.md

Start a new chat after regenerating either file so the tool does not rely on old context.

The Skill Pack Does Not Run Automatically

Some AI tools do not auto-discover project skills. If the skill is installed but not used, reference it directly:

Read .agents/skills/initium/SKILL.md and follow its workflow before changing UI code.

The skill pack should be installed at:

.agents/skills/initium/

If that folder is missing, reinstall the skill pack:

npx shadcn@latest add @initium/initium-agent

The skill pack is a pro item and requires INITIUM_LICENSE_KEY.

Still Stuck

Verify the setup in this order:

1. components.json exists.
2. components.json includes the @initium registry.
3. A free item such as @initium/initium-styles installs.
4. INITIUM_LICENSE_KEY is available for pro items.
5. Initium styles are installed before blocks.
6. DESIGN.md and STRATEGY.md are in the root when using AI tools.