Manual review required for ${issues.length} item${ iss

Error message

Manual review required for ${issues.length} item${
      issues.length === 1 ? "" : "s"
    }:

What it means

When the cn transformer encounters constructs it cannot safely migrate (unsupported clsx/tailwind-merge usage), it collects them as CnMigrationIssue entries. printUnsupportedIssues is called after the migration (or after finding no supported usage) and logs a warning header with the count of items needing manual review, followed by one line per issue. This is a diagnostic warning, not a thrown error; the migration still completes for the files it could change.

Source

Thrown at packages/shadcn/src/migrations/cn/index.ts:177

  )
}

function getDeclaredMajor(version?: string) {
  if (!version || /^(?:workspace|file|link|git|https?):/i.test(version)) {
    return null
  }

  const match = version.match(/(?:^|[^0-9])(\d+)(?:\.|$)/)
  return match ? Number(match[1]) : null
}

function printUnsupportedIssues(issues: CnMigrationIssue[], cwd: string) {
  if (!issues.length) {
    return
  }

  logger.break()
  logger.warn(
    `Manual review required for ${issues.length} item${
      issues.length === 1 ? "" : "s"
    }:`
  )
  for (const issue of issues) {
    const file = issue.file ? path.relative(cwd, issue.file) : "unknown file"
    const symbol = issue.symbol ? ` (${issue.symbol})` : ""
    logger.warn(`  - ${file}${symbol}: ${issue.reason}`)
  }
}

View on GitHub (pinned to 5c7072da67)

Solutions

Read each listed issue (file, symbol, reason) and migrate those spots by hand to the new cn utility.
Update custom cn wrappers to re-export the new `cn` package, then delete the manual item.
Rerun the migration afterwards to confirm the manual-review list is empty.
If an item is intentional legacy code, document it and leave it as-is — the warning is advisory.

Defensive patterns

Strategy: try-catch

Try / catch

await migrateCn({ cwd: process.cwd(), yes: true })
// the CLI prints 'Manual review required...' — capture output in CI and fail if present
if (cliOutput.includes('Manual review required')) {
  throw new Error('Migration finished but manual-review items remain')
}

Prevention

Keep cn() helpers in the standard shape the transformer understands.
Avoid aliasing or dynamically importing clsx/tailwind-merge.
Run the migration on a branch and diff every reported item.
Treat the warning list as a checklist — rerun until it is empty.

When it happens

Trigger: Any migrateCn run where at least one transformed file reports result.unsupported issues — e.g. dynamic imports of clsx/tailwind-merge, non-standard cn definitions, re-exports the transformer cannot rewrite.

Common situations: Custom cn() wrappers in utils.ts that the transformer leaves alone; conditional or aliased imports of tailwind-merge (twMerge); code generated patterns the AST rules don't cover; large legacy codebases with unusual class-merge helpers.

Related errors

AI-assisted analysis of shadcn-ui/ui@5c7072da67 (2026-09-07). Data as JSON: /api/errors/5b5094a5936dfb1e. Report an issue: GitHub.