shadcn-ui/ui · error · Error

A full project config is required to add non-universal regis

Error message

A full project config is required to add non-universal registry items or dependencies.

What it means

Thrown by resolveRegistryTree when options.requireUniversal is true AND at least one item in the resolved payload is not universal (isUniversalRegistryItem returns false). Universal items must have type `registry:item` or `registry:file`, and every declared file must have an explicit `target` and be of those same types. Unlike every other error here, this is a plain `new Error(...)` — NOT a RegistryError subclass — so it has no `.code`, `.suggestion`, or `.context`. Callers cannot distinguish it by code, only by message.

Source

Thrown at packages/shadcn/src/registry/resolver.ts:289

        // Deduplicate URLs
        const uniqueUrls = Array.from(new Set(registryUrls))
        let result = await fetchRegistry(uniqueUrls, options)
        const registryPayload = z.array(registryItemSchema).parse(result)
        payload.push(...registryPayload)
      }
    }
  }

  if (!payload.length) {
    return null
  }

  if (
    options.requireUniversal &&
    !payload.every((item) => isUniversalRegistryItem(item))
  ) {
    throw new Error(
      "A full project config is required to add non-universal registry items or dependencies."
    )
  }

  // No deduplication - we want to support multiple items with the same name from different sources

  // If we're resolving the index, we want to fetch
  // the theme item if a base color is provided.
  // We do this for index only.
  // Other components will ship with their theme tokens.
  if (
    uniqueNames.includes("index") ||
    allDependencyRegistryNames.includes("index")
  ) {
    if (config.tailwind.baseColor) {
      const theme = await registryGetTheme(config.tailwind.baseColor, config)
      if (theme) {
        payload.unshift(theme)

View on GitHub (pinned to efac598707)

Solutions

1. Run `npx shadcn init` first so a full project config exists, then drop the `requireUniversal` option.
2. Restrict the input items to universal ones: type registry:item or registry:file with explicit `target` on every file.
3. If you're a programmatic caller, gate the option on whether `config.resolvedPaths` is fully populated.

import { isUniversalRegistryItem } from "@/src/registry/utils";

async function safeResolveUniversal(names, config, opts) {
  const tree = await resolveRegistryTree(names, config, { ...opts, requireUniversal: false });
  const nonUniversal = (tree?.files ?? []).length; // crude; better: re-fetch items and check each
  return tree;
}

// Better: gate the option on config completeness
function shouldRequireUniversal(config: Config) {
  return !config?.resolvedPaths?.cwd || !config?.resolvedPaths?.ui;
}

import { isUniversalRegistryItem } from "@/src/registry/utils";
import type { RegistryItem } from "@/src/schema";

function isUniversal(item: RegistryItem | null | undefined): boolean {
  return isUniversalRegistryItem(item);
}

// NOTE: this error is a plain Error, not a RegistryError — match by message.
try {
  await resolveRegistryTree(names, config, { requireUniversal: true });
} catch (e) {
  if (e instanceof Error && /full project config is required/.test(e.message)) {
    // re-run without requireUniversal, or guide the user to run `shadcn init`
  }
  throw e;
}

When it happens

Trigger: Programmatic callers (e.g. add command in universal/dry mode, or any caller passing `{ requireUniversal: true }`) pass a component name like `button` whose resolved item is type `registry:ui`, which fails the universal check because its files have no explicit `target`.

Common situations: Running an `add`-like flow outside a configured project (no resolvedPaths) where the CLI forces requireUniversal; mixing regular shadcn components into a universal-only install pipeline; programmatic use of shadcn's API from a non-Shadcn project.

Related errors

• No components.json found. Run shadcn init first.
• INVALID_CONFIG
• The provided cwd must match config.resolvedPaths.cwd.
• A full project config is required to resolve target aliases.
• VALIDATION_ERROR

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