nexu-io/open-design · error · LocalDesignSystemImportError

BAD_REQUEST

BAD_REQUEST

Error message

shadcn reference did not resolve to a usable registry item (no name, cssVars, or files)

What it means

After resolving and fetching a shadcn registry item, the importer checks that the item has at least a name string, a cssVars object, or a non-empty files array (shadcn-import.ts:156). If none are present, the item carries no usable theme or component data and the import is rejected with BAD_REQUEST before any files are written to disk.

Source

Thrown at apps/daemon/src/design-systems/shadcn-import.ts:157

export async function importShadcnDesignSystemProject(
  reference: string,
  tmpRoot: string,
  userDesignSystemsRoot: string,
  options: ShadcnDesignSystemImportOptions = {},
): Promise<LocalDesignSystemImportResult> {
  // One shared budget across every fetch this import makes (resolution +
  // include recursion + file fetches): a request count cap and a wall-clock
  // deadline, layered on top of the per-request timeout.
  const fetchImpl = withFetchBudget(options.fetchImpl ?? defaultShadcnFetch());
  const parsed = parseShadcnReference(reference);
  const importedAt = (options.now ?? new Date()).toISOString();
  const resolved = await resolveShadcnItem(parsed, fetchImpl);
  const item = resolved.item;

  const itemName = typeof item.name === 'string' && item.name.trim() ? item.name.trim() : undefined;
  const hasFiles = Array.isArray(item.files) && item.files.length > 0;
  if (!itemName && !item.cssVars && !hasFiles) {
    throw new LocalDesignSystemImportError(
      'BAD_REQUEST',
      'shadcn reference did not resolve to a usable registry item (no name, cssVars, or files)',
    );
  }

  const materializeRoot = path.join(tmpRoot, 'shadcn-design-system-imports');
  await mkdir(materializeRoot, { recursive: true });
  const tempDir = await mkdtemp(path.join(materializeRoot, 'item-'));

  try {
    await materializeShadcnItem(item, tempDir, resolved, fetchImpl);
    const fallbackName = cleanShadcnName(item.title ?? itemName ?? 'shadcn design system');
    return await importLocalDesignSystemProject(tempDir, userDesignSystemsRoot, {
      now: new Date(importedAt),
      fallbackName,
      ...(options.name ? { name: options.name } : {}),
      ...(options.reservedIds ? { reservedIds: options.reservedIds } : {}),
      ...(options.importMode ? { importMode: options.importMode } : {}),

View on GitHub (pinned to 5be4028344)

Solutions

Fetch the registry URL manually and confirm the resolved item object has a name, cssVars, or files field
If the URL is a registry index (has items or include arrays), append #<item-name> to select a specific item
Verify the item name in the shorthand matches an entry in registry.json's items array

Example fix

// before: registry item is empty
{ "name": "my-theme" }
// after: add cssVars or files
{
  "name": "my-theme",
  "cssVars": { "theme": { "primary": "#0070f3" } }
}

Defensive patterns

Strategy: try-catch

Type guard

// Type guard for a usable shadcn registry item (if you fetch it yourself)
interface ShadcnRegistryItemLike {
  name?: string;
  cssVars?: unknown;
  files?: unknown[];
}

function isUsableRegistryItem(item: unknown): item is ShadcnRegistryItemLike {
  if (typeof item !== 'object' || item === null) return false;
  const c = item as ShadcnRegistryItemLike;
  return (
    (typeof c.name === 'string' && c.name.trim().length > 0) ||
    c.cssVars !== undefined ||
    (Array.isArray(c.files) && c.files.length > 0)
  );
}

Try / catch

import { LocalDesignSystemImportError } from './import.js';

try {
  await importShadcnDesignSystem(reference, tmpRoot, dsRoot, options);
} catch (err) {
  if (err instanceof LocalDesignSystemImportError && err.code === 'BAD_REQUEST') {
    // Surface to user: the registry item is empty or malformed.
    // Suggest verifying the reference URL or item name.
    return { error: err.message };
  }
  throw err;
}

Prevention

Fetch the registry URL manually before importing to confirm the item has name, cssVars, or files
If using a registry index URL, always append #<item-name> to select a specific item
Validate the item name in the shorthand matches an entry in the registry's items array

When it happens

Trigger: Pointing the reference at a registry URL whose resolved item is an empty object {}, or a GitHub shorthand whose registry.json entry for the named item omits name, cssVars, and files.

Common situations: The registry item is a placeholder or stub; the URL points to a registry index document that was mistakenly resolved as a single item; the shadcn registry format changed and the fields the importer expects moved or were renamed.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/c91b35d5746cade0. Report an issue: GitHub.