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 the server rejected it. Common reasons:

• Key is not valid in Lemon Squeezy API.

• Key is mistyped, or contains extra spaces or characters.

• Key belongs to a different product.

• Key was refunded, regenerated or expired.

How to fix it

• Confirm you are using the exact license key from your purchase email or Lemon Squeezy Portal.

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

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.

Still having trouble? Reach out to us