{"record":{"id":"f3e5f02746e27419","repo":"shadcn-ui/ui","slug":"parse-error-f3e5f0","errorCode":"PARSE_ERROR","errorMessage":"Failed to parse registry item: ${item}","messagePattern":"Failed to parse registry item: (.+?)","errorType":"validation","errorClass":"RegistryParseError","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/fetcher.ts","lineNumber":158,"sourceCode":"  return `${url}:${headersHash}`\n}\n\nexport async function fetchRegistryLocal(filePath: string) {\n  try {\n    // Handle tilde expansion for home directory\n    let expandedPath = filePath\n    if (filePath.startsWith(\"~/\")) {\n      expandedPath = path.join(homedir(), filePath.slice(2))\n    }\n\n    const resolvedPath = path.resolve(expandedPath)\n    const content = await fs.readFile(resolvedPath, \"utf8\")\n    const parsed = JSON.parse(content)\n\n    try {\n      return registryItemSchema.parse(parsed)\n    } catch (error) {\n      throw new RegistryParseError(filePath, error)\n    }\n  } catch (error) {\n    // Check if this is a file not found error\n    if (\n      error instanceof Error &&\n      (error.message.includes(\"ENOENT\") ||\n        error.message.includes(\"no such file\"))\n    ) {\n      throw new RegistryLocalFileError(filePath, error)\n    }\n    // Re-throw parse errors as-is\n    if (error instanceof RegistryParseError) {\n      throw error\n    }\n    // For other errors (like JSON parse errors), throw as local file error\n    throw new RegistryLocalFileError(filePath, error)\n  }\n}","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/fetcher.ts#L140-L176","documentation":"Thrown by fetchRegistryLocal when a local file was read and JSON.parse succeeded, but registryItemSchema.parse failed. RegistryParseError wraps the ZodError (printed in the message) and points at the registry-item schema. The file exists and is valid JSON; its contents just do not match a single registry item.","triggerScenarios":"Pointing fetchRegistryLocal at a registry catalog JSON (which has 'items[]') instead of a single registry-item JSON, or at a hand-written item missing required fields (name, type, files with required keys).","commonSituations":"Confusing a catalog file for an item file, editing a local item JSON and dropping a required field, or schema drift after upgrading the CLI's registry-item schema.","solutions":["Read the printed ZodError issues to find the failing field on the item.","Confirm the file is a single item (has name, type, files), not a catalog (which has items[]).","Validate against https://ui.shadcn.com/schema/registry-item.json.","Use loadRegistry/loadRegistryItem for catalog files instead of fetchRegistryLocal."],"exampleFix":"// before: local item file missing required 'type'\n{ \"name\": \"button\", \"files\": [] }\n\n// after\n{\n  \"name\": \"button\",\n  \"type\": \"registry:ui\",\n  \"files\": [{ \"path\": \"button.tsx\", \"type\": \"registry:ui\", \"target\": \"\" }]\n}","handlingStrategy":"validation","validationCode":"import { registryItemSchema } from \"@/src/schema\";\nimport * as fs from \"fs/promises\";\n\nasync function validateLocalItem(filePath: string) {\n  const json = JSON.parse(await fs.readFile(filePath, \"utf8\"));\n  const result = registryItemSchema.safeParse(json);\n  if (!result.success) {\n    throw new Error(`Item schema error: ${result.error.message}`);\n  }\n  return result.data;\n}","typeGuard":"function isRegistryItem(json: unknown): boolean {\n  return registryItemSchema.safeParse(json).success;\n}","tryCatchPattern":"try {\n  await fetchRegistryLocal(filePath);\n} catch (err) {\n  if (err instanceof RegistryParseError) {\n    // err.parseError holds the ZodError; show field-level issues to fix the file\n  }\n  throw err;\n}","preventionTips":["Validate local item files with registryItemSchema before committing.","Use loadRegistryItem for catalog files; fetchRegistryLocal is for single items only.","Keep a JSON schema check in CI for all .json under your registry directory."],"tags":["local-file","parse-error","schema","registry-item","typescript"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}