{"record":{"id":"82e750e524656ce6","repo":"shadcn-ui/ui","slug":"failed-to-fetch-components-from-registry","errorCode":null,"errorMessage":"Failed to fetch components from registry.","messagePattern":"Failed to fetch components from registry\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/add.ts","lineNumber":80,"sourceCode":"          ...inputConfig,\n          resolvedPaths: {\n            ...inputConfig?.resolvedPaths,\n            cwd,\n          },\n        }\n  )\n  const env = await loadEnvFiles(cwd, {\n    processEnv: { ...process.env },\n  })\n\n  return withRegistryContext(\n    async () => {\n      const resolvedTree = await resolveRegistryTree(items, config, {\n        useCache: true,\n        requireUniversal: !parsedConfig.success,\n      })\n      if (!resolvedTree) {\n        throw new Error(\"Failed to fetch components from registry.\")\n      }\n      if (\n        !parsedConfig.success &&\n        !hasResolvedTargetAliases(resolvedTree, config)\n      ) {\n        throw new Error(\n          \"A full project config is required to resolve target aliases.\"\n        )\n      }\n\n      await addComponents(items, config, {\n        ...addComponentsOptions,\n        interactive: false,\n        overwriteCssVars:\n          options.overwriteCssVars ??\n          (parsedConfig.success ? undefined : false),\n        resolvedTree,\n      })","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/add.ts#L62-L98","documentation":"Plain Error thrown when resolveRegistryTree returns a falsy value (null/undefined). resolveRegistryTree returns null when none of the requested items could be fetched/parsed from any configured registry source — every fetch failed or returned nothing. This guard fires before any files are written, treating total resolution failure as fatal.","triggerScenarios":"Passing item names that do not exist in the default or any configured registry; all registry sources are unreachable (network down, 404, auth failure); the registry URL is misconfigured; requireUniversal was set (because the config didn't fully parse) and the universal registry does not contain the items.","commonSituations":"Typo in item name; offline CI; custom registry URL pointing at the wrong host; items that only exist in a namespaced registry that was not configured; auth-required registry without credentials.","solutions":["Verify each item name exists: `curl <REGISTRY_URL>/<item>.json` or check the registry index.","Check network/proxy connectivity to the registry host.","If using namespaced items (@ns/item), ensure `registries` in components.json or package.json maps the namespace to a valid URL.","Provide a full valid Config so requireUniversal is false and all configured registries are consulted.","Retry on transient outages."],"exampleFix":"// before — typo / unknown item\naddRegistryItems(['buton'], { cwd: '/app' })\n\n// after\naddRegistryItems(['button'], { cwd: '/app' })\n\n// or, for a custom registry item, configure it first:\n// components.json -> \"registries\": { \"@mine\": \"https://my.host/r\" }\naddRegistryItems(['@mine/widget'], { cwd: '/app' })","handlingStrategy":"try-catch","validationCode":"import { resolveRegistryTree } from '@/src/registry/resolver'\n\nasync function assertItemsResolvable(items: string[], config: Config) {\n  const tree = await resolveRegistryTree(items, config, { useCache: false })\n  if (!tree) throw new Error(`Items not resolvable from any configured registry: ${items.join(', ')}`)\n}\n\nawait assertItemsResolvable(items, config)","typeGuard":null,"tryCatchPattern":"try {\n  await addRegistryItems(items, { cwd })\n} catch (e) {\n  if (e instanceof Error && e.message === 'Failed to fetch components from registry.') {\n    // retry once, or verify item names against the registry index\n    logger.warn('Registry resolution failed; check item names and network.')\n  } else throw e\n}","preventionTips":["Validate item names against the registry index before scripting installs.","Keep `registries` in components.json pointing at reachable hosts.","Provide a full valid Config so requireUniversal is false and all registries are tried.","Retry transient network failures before aborting."],"tags":["registry","add","network","fetch","resolver"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}