{"record":{"id":"6a3112aa2e3b571b","repo":"shadcn-ui/ui","slug":"parse-error","errorCode":"PARSE_ERROR","errorMessage":"Failed to parse registry catalog: ${item}","messagePattern":"Failed to parse registry catalog: (.+?)","errorType":"validation","errorClass":"RegistryParseError","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/api.ts","lineNumber":182,"sourceCode":"        `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.`,\n        {\n          context: {\n            registry: name,\n            include: registry.include,\n          },\n          suggestion:\n            \"Serve a flattened registry.json for CLI consumers. Source registry.json files with include are supported by shadcn build and loadRegistry().\",\n        }\n      )\n    }\n\n    return registry\n  } catch (error) {\n    if (error instanceof RegistryValidationError) {\n      throw error\n    }\n\n    throw new RegistryParseError(name, error, {\n      subject: \"registry catalog\",\n      suggestion:\n        \"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.\",\n    })\n  }\n}\n\nexport async function getRegistryItems(\n  items: string[],\n  options?: RegistryApiOptions\n) {\n  const { config, useCache = false } = options || {}\n\n  return withRegistryContext(() =>\n    fetchRegistryItems(items, configWithDefaults(config), { useCache })\n  )\n}\n","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/api.ts#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open the URL in a browser and confirm it returns an object with 'name' and 'items' matching the schema.","Validate the JSON against https://ui.shadcn.com/schema/registry.json using a JSON-schema validator.","If you control the server, return the exact catalog shape (name, homepage, items[]).","Check the wrapped ZodError issues (printed in the message) for the precise failing field."],"exampleFix":"// before: endpoint returns an item, not a catalog\n{ \"name\": \"button\", \"type\": \"registry:ui\", \"files\": [] }\n\n// after: endpoint returns a catalog\n{\n  \"name\": \"myui\",\n  \"homepage\": \"https://example.com\",\n  \"items\": [\n    { \"name\": \"button\", \"type\": \"registry:ui\", \"files\": [] }\n  ]\n}","handlingStrategy":"try-catch","validationCode":"import { registrySchema } from \"@/src/schema\";\n\nfunction validateCatalog(json: unknown) {\n  const result = registrySchema.safeParse(json);\n  if (!result.success) {\n    throw new Error(`Catalog schema error: ${result.error.message}`);\n  }\n  return result.data;\n}\n// validate a fetched catalog before handing it to getRegistry consumers","typeGuard":"import { registrySchema } from \"@/src/schema\";\nfunction isRegistryCatalog(json: unknown): boolean {\n  return registrySchema.safeParse(json).success;\n}","tryCatchPattern":"try {\n  await getRegistry(name);\n} catch (err) {\n  if (err instanceof RegistryParseError) {\n    // inspect err.parseError (ZodError) for the failing field and surface to user\n  }\n  throw err;\n}","preventionTips":["Run a JSON-schema validator (registry.json schema) on your served catalog in CI.","Confirm the endpoint returns a catalog object, not a single item.","Pin CLI and registry schema versions together."],"tags":["registry","parse-error","schema","zod","typescript"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}