Could not update components.json. Please manually set `rtl:

Error message

Could not update components.json. Please manually set `rtl: true`.

What it means

Thrown by migrateRtl after a try/catch around reading, parsing, and writing components.json fails for any reason. The original error is swallowed by the catch (no binding), and this generic message is thrown instructing the user to manually set `rtl: true`. The file write is the last step before file transformation, so on failure no files have been transformed yet.

Source

Thrown at packages/shadcn/src/migrations/migrate-rtl.ts:114

      logger.info("Migration cancelled.")
      process.exit(0)
    }
  }

  // Update components.json to set rtl: true.
  const configSpinner = spinner("Updating components.json...").start()
  try {
    const configPath = path.resolve(config.resolvedPaths.cwd, "components.json")
    const existingConfig = JSON.parse(await fs.readFile(configPath, "utf-8"))
    existingConfig.rtl = true
    await fs.writeFile(
      configPath,
      JSON.stringify(existingConfig, null, 2) + "\n"
    )
    configSpinner.succeed("Updated components.json.")
  } catch {
    configSpinner.fail("Failed to update components.json.")
    throw new Error(
      "Could not update components.json. Please manually set `rtl: true`."
    )
  }

  // Transform files.
  const migrationSpinner = spinner("Migrating files to RTL...").start()
  let transformedCount = 0
  const filesNeedingReview: string[] = []

  await Promise.all(
    files.map(async (file) => {
      migrationSpinner.text = `Migrating ${file}...`

      const filePath = path.join(basePath, file)
      const content = await fs.readFile(filePath, "utf-8")
      const transformed = await transformDirection(content, true)

      // Only write if content changed.

View on GitHub (pinned to efac598707)

Solutions

Manually edit components.json to add `"rtl": true` at the top level.
Verify components.json exists at the project root and is valid JSON (`node -e "JSON.parse(require('fs').readFileSync('components.json'))"`).
Check write permissions on the file and directory (`ls -l components.json`).
If running in CI, ensure the working directory is writable.

Example fix

// before — components.json missing or invalid
// (the migrator failed to update it)

// after — manually add the rtl flag
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rtl": true,
  "aliases": { ... }
}

Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'fs/promises'
import path from 'path'

async function assertComponentsJsonWritable(cwd: string) {
  const p = path.resolve(cwd, 'components.json')
  const txt = await fs.readFile(p, 'utf-8')
  JSON.parse(txt) // throws on invalid JSON
  await fs.access(path.dirname(p), fs.constants.W_OK)
}

await assertComponentsJsonWritable(config.resolvedPaths.cwd)

Try / catch

try {
  await migrateRtl(config, { yes: true })
} catch (e) {
  if (e instanceof Error && e.message.includes('manually set `rtl: true`')) {
    logger.warn('Auto-update of components.json failed. Edit it manually to add "rtl": true, then re-run.')
    // optionally write the flag yourself with a known-good serializer
  } else throw e
}

Prevention

Validate components.json parses with `JSON.parse` before running.
Ensure the project directory is writable in CI containers.
Keep components.json under source control so corruption is caught in review.

When it happens

Trigger: components.json does not exist at config.resolvedPaths.cwd; the file exists but contains invalid JSON; the file is read-protected or the directory is read-only; a PermissionError or disk error during writeFile.

Common situations: Running in a read-only filesystem (CI container with mounted read-only config); components.json was renamed/moved after init; JSON was hand-edited and broke syntax; permissions issue.

Related errors

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