shadcn-ui/ui · error · Error

Could not resolve the following aliases in ${highlighter.inf

Error message

Could not resolve the following aliases in ${highlighter.info(cwd)}: ${highlighter.info(missingAliases.join(", "))}.
Configure path aliases in ${highlighter.info("tsconfig.json")} or imports in ${highlighter.info("package.json")} for this workspace and try again.

What it means

Thrown by assertResolvedAliases when one or more of the required aliases (components, ui, lib, hooks, utils) resolve to null after resolveAliasPath consults tsconfig paths and package imports. shadcn needs all five alias roots to know where to write files, so any unresolved alias aborts config resolution.

Source

Thrown at packages/shadcn/src/utils/get-config.ts:180

  return resolved.path
}

function assertResolvedAliases(
  cwd: string,
  resolvedAliases: Record<
    "components" | "utils" | "ui" | "lib" | "hooks",
    string | null
  >
) {
  const missingAliases = ["components", "ui", "lib", "hooks", "utils"].filter(
    (key) => !resolvedAliases[key as keyof typeof resolvedAliases]
  )

  if (!missingAliases.length) {
    return
  }

  throw new Error(
    [
      `Could not resolve the following aliases in ${highlighter.info(cwd)}: ${highlighter.info(
        missingAliases.join(", ")
      )}.`,
      `Configure path aliases in ${highlighter.info(
        "tsconfig.json"
      )} or imports in ${highlighter.info(
        "package.json"
      )} for this workspace and try again.`,
    ].join("\n")
  )
}

export async function getRawConfig(
  cwd: string
): Promise<z.infer<typeof rawConfigSchema> | null> {
  try {
    const configResult = await explorer.search(cwd)

View on GitHub (pinned to efac598707)

Solutions

1. Open tsconfig.json and add/fix the "paths" entries for each alias listed in the message (e.g. "@/components/*", "@/lib/utils", "@/hooks/*").
2. Or add matching "imports" entries in package.json if you use subpath imports.
3. Re-run `npx shadcn@latest init` to regenerate components.json aliases against the fixed tsconfig.
4. Verify the alias prefixes in components.json match the tsconfig paths exactly.

Example fix

// tsconfig.json (before)
{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
// components.json references aliases that don't resolve -> error
// after — ensure each alias resolves; e.g. add explicit paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/utils": ["./src/lib/utils"],
      "@/hooks/*": ["./src/hooks/*"]
    }
  }
}

import { loadConfig } from "tsconfig-paths"
const ts = await loadConfig(cwd)
const required = ["components", "ui", "lib", "hooks", "utils"]
const missing = required.filter((k) => !resolveAlias(config.aliases[k], ts))
if (missing.length) throw new Error(`unresolved aliases: ${missing.join(", ")}`)

function aliasesResolve(config, ts): boolean {
  return ["components", "ui", "lib", "hooks", "utils"].every((k) =>
    !!resolveImportWithMetadata(config.aliases[k], { ...ts, cwd })?.path
  )
}

try {
  await resolveConfigPaths(cwd, config)
} catch (e) {
  if (e instanceof Error && /Could not resolve the following aliases/.test(e.message)) {
    // prompt to fix tsconfig paths
  }
  throw e
}

When it happens

Trigger: resolveConfigPaths calls resolveAliasPath for each alias; if the alias string is not found in tsconfig "paths", package.json "imports", or workspace exports, it returns null. assertResolvedAliases collects every null key and throws if the list is non-empty.

Common situations: Fresh project where tsconfig paths do not cover components/ui/lib/hooks/utils; components.json aliases reference a prefix that was never declared; switched from paths to package "imports" but did not wire them; monorepo where the alias resolves only in a different package.

Related errors

• Failed to load ${config.tsx ? "tsconfig" : "jsconfig"}.json.
• No `components.json` file found. Ensure you are at the root
• No components.json found. Run shadcn init first.
• A full project config is required to resolve target aliases.
• INVALID_CONFIG

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