{"record":{"id":"6ba383e9248b824b","repo":"shadcn-ui/ui","slug":"not-found","errorCode":"NOT_FOUND","errorMessage":"The item at ${url} was not found. It may not exist at the registry.","messagePattern":"The item at (.+?) was not found\\. It may not exist at the registry\\.","errorType":"http","errorClass":"RegistryNotFoundError","httpStatus":404,"severity":"error","filePath":"packages/shadcn/src/registry/api.ts","lineNumber":140,"sourceCode":"    return fetchGitHubRegistryCatalog(githubSource, { useCache })\n  }\n\n  if (!name.startsWith(\"@\")) {\n    throw new RegistryInvalidNamespaceError(name)\n  }\n\n  let registryName = name\n  if (!registryName.endsWith(\"/registry\")) {\n    registryName = `${registryName}/registry`\n  }\n\n  const urlAndHeaders = buildUrlAndHeadersForRegistryItem(\n    registryName as `@${string}`,\n    configWithDefaults(config)\n  )\n\n  if (!urlAndHeaders?.url) {\n    throw new RegistryNotFoundError(registryName)\n  }\n\n  // Append search params before registering headers so the header lookup key\n  // matches the URL we actually fetch.\n  const url = appendSearchParamsToUrl(urlAndHeaders.url, searchParams)\n\n  if (urlAndHeaders.headers && Object.keys(urlAndHeaders.headers).length > 0) {\n    setRegistryHeaders({\n      [url]: urlAndHeaders.headers,\n    })\n  }\n\n  const [result] = await fetchRegistry([url], { useCache })\n\n  return parseRegistryCatalog(registryName, result)\n}\n\nfunction parseRegistryCatalog(name: string, result: unknown) {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/api.ts#L122-L158","documentation":"Thrown by getRegistryWithContext when buildUrlAndHeadersForRegistryItem returns a result whose url is missing. In practice the builder returns null for inputs it considers URL/local-file/local-path/GitHub-address forms; since the URL and GitHub branches are handled earlier in getRegistryWithContext, this fires when a local file path or local path string reaches the namespace-resolution path.","triggerScenarios":"Calling getRegistry() with a string that starts with './' or '/' (a local path) or is otherwise treated as local, so buildUrlAndHeadersForRegistryItem short-circuits to null and urlAndHeaders?.url is undefined.","commonSituations":"Passing a relative or absolute filesystem path to getRegistry (which expects a registry namespace, URL, or GitHub source). Mixing up the local loader (loadRegistry) with the remote registry catalog fetcher.","solutions":["If you want to load a local registry file, use loadRegistry({ registryFile: \"...\" }) from the loader module instead of getRegistry().","If you want a remote registry, pass its full URL (http/https) or an '@namespace' name.","If you want a GitHub source, use the owner/repo form.","Strip leading './' or '/' if you intended a namespace name."],"exampleFix":"// before\ngetRegistry(\"./registry.json\")\n\n// after\nimport { loadRegistry } from \"@/src/registry/loader\"\nawait loadRegistry({ registryFile: \"./registry.json\" })","handlingStrategy":"validation","validationCode":"import { isUrl } from \"@/src/registry/utils\";\nimport { resolveGitHubRegistrySource } from \"@/src/registry/address\";\n\nfunction chooseRegistryLoader(name: string) {\n  if (isUrl(name)) return \"remote\";\n  if (name.startsWith(\"./\") || name.startsWith(\"/\")) return \"local-loader\";\n  if (resolveGitHubRegistrySource(name)) return \"github\";\n  if (name.startsWith(\"@\")) return \"namespace\";\n  throw new Error(`Cannot resolve registry reference: ${name}`);\n}\n// route './foo.json' to loadRegistry, not getRegistry","typeGuard":"function isLocalRegistryRef(name: string): boolean {\n  return name.startsWith(\"./\") || name.startsWith(\"/\") || name.startsWith(\"~/\");\n}","tryCatchPattern":"try {\n  await getRegistry(name);\n} catch (err) {\n  if (err instanceof RegistryNotFoundError && isLocalRegistryRef(name)) {\n    // fall back to the local loader\n    return loadRegistry({ registryFile: name });\n  }\n  throw err;\n}","preventionTips":["Use loadRegistry() for local files; reserve getRegistry() for URLs, namespaces, GitHub sources.","Add an input router at the call site so paths never reach the namespace branch.","Unit-test the routing decision before invoking the network path."],"tags":["registry","not-found","local-file","typescript"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}