shadcn-ui/ui · error · RegistryParseError

PARSE_ERROR

PARSE_ERROR

Error message

Failed to parse registry catalog: ${item}

What it means

Thrown by parseRegistryCatalog as a fallback when registrySchema.parse(result) fails for any reason other than the explicit 'include' validation. The wrapped error is typically a ZodError describing which fields violated the registry.json schema. The message points at https://ui.shadcn.com/schema/registry.json for the canonical shape.

Source

Thrown at packages/shadcn/src/registry/api.ts:182

        `Registry catalog "${name}" uses "include", but consumer registry endpoints must serve a resolved registry catalog. Run "npx shadcn build" and serve the built registry.json, or use loadRegistry() in a dynamic route.`,
        {
          context: {
            registry: name,
            include: registry.include,
          },
          suggestion:
            "Serve a flattened registry.json for CLI consumers. Source registry.json files with include are supported by shadcn build and loadRegistry().",
        }
      )
    }

    return registry
  } catch (error) {
    if (error instanceof RegistryValidationError) {
      throw error
    }

    throw new RegistryParseError(name, error, {
      subject: "registry catalog",
      suggestion:
        "The registry catalog may be corrupted or have an invalid format. Please make sure it returns a valid registry.json object. See https://ui.shadcn.com/schema/registry.json.",
    })
  }
}

export async function getRegistryItems(
  items: string[],
  options?: RegistryApiOptions
) {
  const { config, useCache = false } = options || {}

  return withRegistryContext(() =>
    fetchRegistryItems(items, configWithDefaults(config), { useCache })
  )
}

View on GitHub (pinned to efac598707)

Solutions

1. Open the URL in a browser and confirm it returns an object with 'name' and 'items' matching the schema.
2. Validate the JSON against https://ui.shadcn.com/schema/registry.json using a JSON-schema validator.
3. If you control the server, return the exact catalog shape (name, homepage, items[]).
4. Check the wrapped ZodError issues (printed in the message) for the precise failing field.

Example fix

// before: endpoint returns an item, not a catalog
{ "name": "button", "type": "registry:ui", "files": [] }

// after: endpoint returns a catalog
{
  "name": "myui",
  "homepage": "https://example.com",
  "items": [
    { "name": "button", "type": "registry:ui", "files": [] }
  ]
}

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

function validateCatalog(json: unknown) {
  const result = registrySchema.safeParse(json);
  if (!result.success) {
    throw new Error(`Catalog schema error: ${result.error.message}`);
  }
  return result.data;
}
// validate a fetched catalog before handing it to getRegistry consumers

import { registrySchema } from "@/src/schema";
function isRegistryCatalog(json: unknown): boolean {
  return registrySchema.safeParse(json).success;
}

try {
  await getRegistry(name);
} catch (err) {
  if (err instanceof RegistryParseError) {
    // inspect err.parseError (ZodError) for the failing field and surface to user
  }
  throw err;
}

When it happens

Trigger: A registry endpoint returns JSON that does not match registrySchema: missing 'name', missing 'items', wrong item shape, wrong type values, or unexpected/typo'd field names. Also triggered by a 200 response that returns an HTML error page parsed as JSON, or an object wrapped one level too deep/shallow.

Common situations: Hand-editing a registry.json and introducing a schema drift, pointing getRegistry at the wrong URL (e.g., an item JSON instead of a catalog), or a registry server returning a legacy/incompatible format after an upgrade.

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
• PARSE_ERROR
• Invalid registry schema for ${base.name}
• Invalid registry schema for ${style.name}

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