---
title: Troubleshooting
description: Fix common Initium setup issues with shadcn, registry configuration, license keys, styles, and AI assets.
slug: troubleshooting
order: 7
---

# 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:

```bash
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:

```bash
npx shadcn@latest add @initium/initium-styles
```

Check that `components.json` includes the Initium registry:

```json
{
  "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:

```bash
INITIUM_LICENSE_KEY=your_polar_license_key
```

Then retry the pro install:

```bash
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:

```bash
npx shadcn@latest add @initium/initium-styles
```

Or install the generated Style Builder preset:

```bash
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:

```bash
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:

```txt
DESIGN.md
STRATEGY.md
```

Then explicitly ask the tool to read them:

```txt
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:

```txt
.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:

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

The skill pack should be installed at:

```txt
.agents/skills/initium/
```

If that folder is missing, reinstall the skill pack:

```bash
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.