shadcn-ui/ui · error · RegistryParseError

PARSE_ERROR

PARSE_ERROR

Error message

Failed to parse registry item: ${item}

What it means

Thrown by fetchRegistryItems when a registry item fetched from a direct URL passes the HTTP fetch but fails validation against registryItemSchema. The endpoint was reachable, but the returned JSON does not conform to the shadcn registry-item schema (missing name/type, wrong type enum value, malformed files, etc.). The underlying ZodError is wrapped in a RegistryParseError so callers see a single, consistent parse-failure type.

Source

Thrown at packages/shadcn/src/registry/resolver.ts:108

  const results = await Promise.all(
    items.map(async (item) => {
      const resolvedAddress = resolveItemAddress(item)

      if (resolvedAddress.scheme === "github") {
        return fetchGitHubRegistryItem(resolvedAddress, options)
      }

      if (isLocalFile(item)) {
        return fetchRegistryLocal(item)
      }

      if (isUrl(item)) {
        const [result] = await fetchRegistry([item], options)
        try {
          return registryItemSchema.parse(result)
        } catch (error) {
          throw new RegistryParseError(item, error)
        }
      }

      if (item.startsWith("@") && config?.registries) {
        const paths = resolveRegistryItemsFromRegistries([item], config)
        const [result] = await fetchRegistry(paths, options)
        try {
          return registryItemSchema.parse(result)
        } catch (error) {
          throw new RegistryParseError(item, error)
        }
      }

      const path = `styles/${config?.style ?? "new-york-v4"}/${item}.json`
      const [result] = await fetchRegistry([path], options)
      try {
        return registryItemSchema.parse(result)
      } catch (error) {

View on GitHub (pinned to efac598707)

Solutions

1. Open the URL in a browser and confirm the body has `name`, a valid `type` (one of registryItemTypeSchema's enum values, e.g. registry:ui), and a well-formed `files` array.
2. Diff the payload against https://ui.shadcn.com/schema/registry-item.json and add/fix the fields flagged by the Zod error in the message.
3. Have the registry author republish the item matching the current schema; if you control the URL, fix the JSON on the server.
4. If the URL is wrong, re-run `shadcn add` with the corrected URL.

Example fix

// before — payload at https://example.com/button.json
{
  "name": "button",
  "files": [{ "path": "button.tsx" }]
}

// after — type added so registryItemSchema accepts it
{
  "name": "button",
  "type": "registry:ui",
  "files": [{ "path": "button.tsx" }]
}

import { registryItemSchema } from "@/src/schema";

async function preValidateUrl(url: string) {
  const res = await fetch(url);
  const json = await res.json();
  const r = registryItemSchema.safeParse(json);
  if (!r.success) {
    return { ok: false, issues: r.error.issues };
  }
  return { ok: true, item: r.data };
}

import { registryItemSchema } from "@/src/schema";

function isRegistryItem(v: unknown): v is z.infer<typeof registryItemSchema> {
  return registryItemSchema.safeParse(v).success;
}

import { RegistryParseError } from "@/src/registry/errors";

try {
  await resolveRegistryItems([url], config, opts);
} catch (e) {
  if (e instanceof RegistryParseError) {
    console.error("Item at", e.item, "failed schema:", e.parseError);
  }
  throw e;
}

When it happens

Trigger: Calling resolveRegistryItems / the `add` flow with a URL argument like `npx shadcn add https://example.com/button.json` where the response body is JSON but does not satisfy registryItemSchema (e.g. missing `type`, unknown `type` string, files array with wrong shape).

Common situations: A third-party registry author shipped a payload for an older or newer schema than the consumer's shadcn version; the URL returns an error envelope (e.g. `{"error":"..."}`) with HTTP 200 instead of a registry item; a typo'd URL hits an unrelated JSON endpoint; server returns HTML that happens to parse.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• INVALID_CONFIG
• PARSE_ERROR
• Invalid registry schema for ${base.name}
• Invalid registry schema for ${style.name}
• Invalid registry schema for ${styleName}

AI-assisted analysis of shadcn-ui/ui@efac598707 (2026-08-12). Data as JSON: /api/errors/231631a50734ed42. Report an issue: GitHub.