Troubleshooting shadcncraft Registry

This guide covers the most common issues when installing components from the shadcncraft private registry (@shadcncraft) using the shadcn CLI.

If you have not yet configured the registry, start with the installation guide.

Validation responses

The Validate license page runs the same license check as the registry. The JSON includes ok, code, message, helpUrls, and a license object when the API returns one, with activation limit, count, current instance, and Polar status.

When validation succeeds, code is granted:

When validation fails, see the sections below. Error alerts list helpUrls as links. The raw JSON at the bottom of the validate page is the full response.

Registry / CLI 401: the body is the message text. If helpUrls are present, the API appends them for plain-text clients: message -> url1 | url2.

1. Missing license key

Error message

Missing license key. Provide a valid license key.

Cause

The request to the registry did not include the X-License-Key header. Common reasons:

• SHADCNCRAFT_LICENSE_KEY is missing or empty.
• Incorrect components.json headers.

How to fix it

Ensure .env or .env.local defines SHADCNCRAFT_LICENSE_KEY and components.json passes "X-License-Key": "${SHADCNCRAFT_LICENSE_KEY}".

2. Invalid license key prefix

Error message

Invalid license key. Missing expected prefix. If you previously purchased the Pro React shadcn/ui Kit and had a valid license key, please contact support so we can provide you with a new license.

Cause

The key does not use the expected prefix—such as an old key from before the Polar migration, a typo, or a key for another product.

How to fix it

• Use a key that starts with SHADCNCRAFT.
• Retrieve the current key from the Polar Portal or your purchase email. If it still fails, contact support.

3. License key not recognized

Error message

License key not recognized. Double-check the key or contact support.

With links:

License key not recognized. Double-check the key or contact support. -> https://shadcncraft.com/support | https://polar.sh/shadcraft/portal/request

Cause

The key was sent but is not known to the licensing system: typo, wrong product, or key never issued.

How to fix it

Copy the key exactly from Polar, with no extra spaces. Confirm it is for the Pro + React shadcn/ui Kit.

4. Temporary validation failure

Error message

Unable to validate license right now. Try again.

With links:

Unable to validate license right now. Try again. -> https://shadcncraft.com/support

Cause

Transient failure while contacting the licensing backend.

How to fix it

Retry after a short wait. If it persists, contact support.

5. License grant or key inactive

Revoked or disabled key

Polar code is revoked or disabled.

Message:

This license key has been <status>. Contact support for assistance.

<status> is the Polar license status, such as revoked or disabled.

Grant inactive

Message:

This license grant is no longer active. Contact support.

Cause

Refund, revocation, disabled key, or benefit not granted.

How to fix it

Contact support and check the Polar Portal for your order.

6. Activation required

Polar code is activation_required.

Single and Team licenses use activations. The registry needs your license key and an instance that was activated on Activate license. Validate license does not activate; it only checks.

If you forgot your instance name or are not sure which label to use, open the Polar Portal and review your activations. Older customers may see a legacy instance name DEFAULT from an earlier activation flow—use that exact string in SHADCNCRAFT_INSTANCE_NAME if it matches what Polar shows.

Possible message values:

helpUrls often list Activate license, support, or the Polar Portal request page.

How to fix it

1. Complete activation if you have not.
2. Set SHADCNCRAFT_INSTANCE_NAME to the exact string used at activation.
3. Confirm activations in the Polar Portal. If you are unsure of the label, review what is registered there before changing env vars.

7. Activation limit reached

Error message

Activation limit reached. Deactivate or manage your activations in the Polar Portal or upgrade your plan.

With links:

Activation limit reached. Deactivate or manage your activations in the Polar Portal or upgrade your plan. -> https://shadcncraft.com/support | https://polar.sh/shadcraft/portal/request

Cause

The license allows a fixed number of activations and the limit is full.

How to fix it

• Free a seat in the Polar Portal by deactivating an instance you no longer use.
• Purchase a tier or add-on with more activations if your one-time order included a seat limit you have outgrown.
• Contact support if you are stuck.

8. Unknown registry "@shadcncraft"

CLI output

Unknown registry "@shadcncraft". Make sure it is defined in components.json as follows:
 
{
  "registries": {
    "@shadcncraft": "[URL_TO_REGISTRY]"
  }
}

Cause

components.json is missing the @shadcncraft registry entry or the name is wrong.

How to fix it

Add the block from the installation guide. The key must be exactly @shadcncraft.

9. Invalid registry configuration

Error message

Invalid configuration found in components.json. Invalid configuration in components.json.

Common causes

Missing @ prefix

// ❌ Incorrect
"registries": {
  "shadcncraft": { ... }
}
 
// ✅ Correct
"registries": {
  "@shadcncraft": { ... }
}

Missing /{name} suffix in URL

The shadcn CLI requires the {name} placeholder in every registry URL. Both templates below are valid — use the style-aware one if you want components.json#style to select the variant.

// ❌ Incorrect
"url": "https://shadcncraft.com/r"
 
// ✅ Correct (style-aware, recommended)
"url": "https://shadcncraft.com/r/{style}/{name}"
 
// ✅ Correct (name-only, legacy variant locks to style `new-york-v4`)
"url": "https://shadcncraft.com/r/{name}"

How to fix it

Match the installation snippet and validate JSON syntax.

10. CLI crashes during installation

Example CLI output

? The file button.tsx already exists. Would you like to overwrite? » (y/N) TypeError: Cannot read properties of undefined (reading 'toLowerCase')

Cause

A shadcn CLI bug during overwrite prompts, or a terminal glitch. Not specific to shadcncraft.

How to fix it

Rerun the command or restart the terminal.

11. Activation flow errors

These appear on Activate license, not when running the shadcn CLI against the registry:

Use Activate license to activate. Use Validate license to verify without changing state.

Still having trouble? Reach out to us