shadcn-ui/ui · warning

You must specify a migration. Run `shadcn migrate --list` to

Error message

You must specify a migration. Run `shadcn migrate --list` to see available migrations.

What it means

Defensive guard intended to ensure a migration name was supplied. Note: the early-return at migrate.ts:79 already lists and returns when --list is set OR options.migration is falsy, so control only reaches line 87 when options.migration is already truthy. Under the current flow this branch is effectively dead code — kept as a safety net.

Source

Thrown at packages/shadcn/src/commands/migrate.ts:88

        cwd: path.resolve(opts.cwd),
        migration,
        path: migratePath,
        list: opts.list,
        yes: opts.yes,
        from: opts.from,
        to: opts.to,
      })

      if (options.list || !options.migration) {
        logger.info("Available migrations:")
        for (const migration of migrations) {
          logger.info(`- ${migration.name}: ${migration.description}`)
        }
        return
      }

      if (!options.migration) {
        throw new Error(
          "You must specify a migration. Run `shadcn migrate --list` to see available migrations."
        )
      }

      let { errors, config } = await preFlightMigrate(options)

      if (
        errors[ERRORS.MISSING_DIR_OR_EMPTY_PROJECT] ||
        errors[ERRORS.MISSING_CONFIG]
      ) {
        throw new Error(
          "No `components.json` file found. Ensure you are at the root of your project."
        )
      }

      if (!config) {
        throw new Error(
          "Something went wrong reading your `components.json` file. Please ensure you have a valid `components.json` file."

View on GitHub (pinned to efac598707)

Solutions

1. Pass a migration name: `shadcn migrate icons` (or radix, rtl).
2. Run `shadcn migrate --list` to see valid names.
3. If maintaining this code, reconcile lines 79 and 87 to remove the redundant check.

// The early-return at migrate.ts:79 already handles the falsy case.
// If you refactor that, keep an explicit guard:
if (!options.migration && !options.list) {
  throw new Error("You must specify a migration. Run `shadcn migrate --list`.")
}

When it happens

Trigger: Not reachable through the CLI in current versions. Would only fire if the line-79 short-circuit were removed or its condition changed in a future refactor.

Common situations: Not user-reachable today; relevant only to maintainers refactoring the migrate command dispatcher.

Related errors

• Something went wrong reading your `components.json` file. Pl
• File not found: ${options.path}
• Unsupported path type: ${options.path}
• Base color "${baseColorName}" or theme "${themeName}" not fo
• Unknown item: "${designSystemConfig.item}".

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