shadcn-ui/ui · error

Failed to fetch components from registry.

Error message

Failed to fetch components from registry.

What it means

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.

Source

Thrown at packages/shadcn/src/registry/add.ts:80

          ...inputConfig,
          resolvedPaths: {
            ...inputConfig?.resolvedPaths,
            cwd,
          },
        }
  )
  const env = await loadEnvFiles(cwd, {
    processEnv: { ...process.env },
  })

  return withRegistryContext(
    async () => {
      const resolvedTree = await resolveRegistryTree(items, config, {
        useCache: true,
        requireUniversal: !parsedConfig.success,
      })
      if (!resolvedTree) {
        throw new Error("Failed to fetch components from registry.")
      }
      if (
        !parsedConfig.success &&
        !hasResolvedTargetAliases(resolvedTree, config)
      ) {
        throw new Error(
          "A full project config is required to resolve target aliases."
        )
      }

      await addComponents(items, config, {
        ...addComponentsOptions,
        interactive: false,
        overwriteCssVars:
          options.overwriteCssVars ??
          (parsedConfig.success ? undefined : false),
        resolvedTree,
      })

View on GitHub (pinned to efac598707)

Solutions

1. Verify each item name exists: `curl <REGISTRY_URL>/<item>.json` or check the registry index.
2. Check network/proxy connectivity to the registry host.
3. If using namespaced items (@ns/item), ensure `registries` in components.json or package.json maps the namespace to a valid URL.
4. Provide a full valid Config so requireUniversal is false and all configured registries are consulted.
5. Retry on transient outages.

Example fix

// before — typo / unknown item
addRegistryItems(['buton'], { cwd: '/app' })

// after
addRegistryItems(['button'], { cwd: '/app' })

// or, for a custom registry item, configure it first:
// components.json -> "registries": { "@mine": "https://my.host/r" }
addRegistryItems(['@mine/widget'], { cwd: '/app' })

import { resolveRegistryTree } from '@/src/registry/resolver'

async function assertItemsResolvable(items: string[], config: Config) {
  const tree = await resolveRegistryTree(items, config, { useCache: false })
  if (!tree) throw new Error(`Items not resolvable from any configured registry: ${items.join(', ')}`)
}

await assertItemsResolvable(items, config)

try {
  await addRegistryItems(items, { cwd })
} catch (e) {
  if (e instanceof Error && e.message === 'Failed to fetch components from registry.') {
    // retry once, or verify item names against the registry index
    logger.warn('Registry resolution failed; check item names and network.')
  } else throw e
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to fetch components from registry.
• Failed to fetch registry item: ${response.statusText}
• Failed to fetch registries.
• Something went wrong fetching the registry icons.
• Failed to fetch components from registry.

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