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

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

1. Missing license key

Error message

Missing license key. Provide a valid license key

Cause

This happens when the request to the registry does not include the 'X-License-Key' header. Common reasons:

• 'SHADCRAFT_LICENSE_KEY' environment variable is missing.

• Environment variable is empty

• Incorrect 'components.json' headers.

How to fix it

1. Verify environment variable

Ensure your '.env' or '.env.local' file in the project root contains:

SHADCRAFT_LICENSE_KEY="your_license_key"

2. Verify 'components.json' registry configuration

Make sure the '@shadcraft' entry is present and uses the environment variable in the header:

"registries": {
    "@shadcraft": {
      "url": "https://registry-shadcraft.vercel.app/r/{name}",
      "headers": {
        "X-License-Key": "${SHADCRAFT_LICENSE_KEY}"
      }
    }
  }

2. Invalid license key

Error message

Invalid license key. Provide a valid license key

Cause

The license key was sent to the registry, but it does not have the required `SHADCRAFT` prefix. Common reasons:

• You are using an old license key from before the Polar migration.

• The key is mistyped or incomplete.

• The key belongs to a different product.

How to fix it

• Ensure your license key starts with SHADCRAFT.

• If you previously purchased the Pro React shadcn/ui Kit and have an old license key, you can access your new license from the Polar Portal using the same email used to purchase the product.

• If you still can't see your new license in the Polar Portal, contact support.

3. Unknown registry "@shadcraft"

CLI output

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

Cause

Your 'components.json' file is missing the '@shadcraft' block inside the 'registries' section, or the key is mis-typed.

How to fix it

1. Add the complete configuration to 'components.json'

"registries": {
    "@shadcraft": {
      "url": "https://registry-shadcraft.vercel.app/r/{name}",
      "headers": {
        "X-License-Key": "${SHADCRAFT_LICENSE_KEY}"
      }
   }
}

2. Confirm the registry key

• The registry key must be exactly "@shadcraft".

• Do not omit the '@' prefix and do not change the name.

4. Invalid registry configuration

Error message

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

Common causes

Missing '@' prefix

// ❌ Incorrect
"registries": {
  "shadcraft": { ... }
}

// ✅ Correct
"registries": {
  "@shadcraft": { ... }
}

Missing '/{name}' suffix in URL

// ❌ Incorrect
"url": "https://registry-shadcraft.vercel.app/r"

// ✅ Correct
"url": "https://registry-shadcraft.vercel.app/r/{name}"

How to fix it

Use the exact recommended configuration and validate your JSON format:

"@shadcraft": {
  "url": "https://registry-shadcraft.vercel.app/r/{name}",
  "headers": {
    "X-License-Key": "${SHADCRAFT_LICENSE_KEY}"
  }
}

5. 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

The shadcn CLI crashed while prompting for confirmation (for example, when asking to overwrite an existing file). This is typically:

• A bug or edge case in the shadcn CLI or an underlying library.

• A terminal / shell glitch or interrupted prompt.

• Not related to the Shadcraft registry itself.

How to fix it

• Simply rerun the command.

npx shadcn@latest add @shadcraft/faqs-1

If the issue persists, reset your terminal and try again.

6. License key not found

Error message

License key not found. Please check your license key is correct.

Cause

The license key was sent but could not be found in our system. Common reasons:

• Key is mistyped or contains extra spaces/characters.

• Key was never issued or does not exist.

• Key belongs to a different product or organization.

How to fix it

• Confirm you are using the exact license key from your purchase email or Polar Portal

• Ensure there are no extra spaces, quotes, or hidden characters.

• Double-check that the key was issued for the Pro React shadcn/ui Kit.

7. Activation limit reached

Error message

License key activation limit reached. Deactivate an existing activation instance or upgrade your plan.

Cause

Your license key has a maximum number of allowed activations (devices/instances), and that limit has been reached.

How to fix it

• Option 1: Deactivate an existing activation instance from your Polar Portal

• Option 2: Upgrade your plan to increase the activation limit.

• Option 3: Contact support for assistance.

8. License key revoked or not granted

Error message

Your license key has been revoked or has not been granted. Please contact support.

Cause

Your license key exists, but the associated benefit grant has been revoked or was never granted. Common reasons:

• Purchase was refunded.

• Benefit was manually revoked.

How to fix it

• Contact support to clarify the status of your license.

• If you refunded and repurchased, ensure you are using the new license key.

9. License key revoked

Error message

This license key has been revoked. Please contact support.

Cause

The license key has been explicitly revoked in Polar. This typically happens after a refund or policy violation.

How to fix it

• Contact support to understand why your license was revoked.

• If eligible, request a new license key.

10. License key disabled

Error message

This license key has been disabled. Please contact support.

Cause

The license key has been disabled and is no longer valid for use.

How to fix it

• Contact support to understand why your license was disabled.

• If the issue is resolved, request re-enabling or a new license key.

11. Activation failed

Error message

Failed to activate license. Please try again later.

or

Failed to activate license. Please try again or contact support.

Cause

The license activation process failed unexpectedly. This could be a temporary issue with the activation service.

How to fix it

• Wait a few minutes and try again.

• If the issue persists, contact support with your license key (masked) and the error details.

12. Internal server error

Error message

An unexpected error occurred while validating your license key.

or

Server configuration error. Please contact support.

Cause

An unexpected error occurred on the server side while processing your request.

How to fix it

• Wait a few minutes and try again.

• If the issue persists, contact support with details about the error and the command you were running.

Still having trouble? Reach out to us