Failed to run "${command}" to migrate the legacy ESLint conf

Error message

Failed to run "${command}" to migrate the legacy ESLint config "${eslintConfigFilename}".
Please try the migration to Flat config manually.
Learn more: https://eslint.org/docs/latest/use/configure/migration-guide

What it means

Thrown by the next-lint-to-eslint-cli codemod when the `npx @eslint/migrate-config <path>` command itself fails (execSync throws). The codemod wraps the failure with guidance to attempt the flat config migration manually and links to the ESLint migration guide. The original error is attached as `cause`.

Source

Thrown at packages/next-codemod/transforms/next-lint-to-eslint-cli.ts:1121

        execSync(command, {
          cwd: projectRoot,
          stdio: 'pipe',
        })

        // The migration tool creates eslint.config.mjs by default
        const outputPath = path.join(projectRoot, 'eslint.config.mjs')
        if (!existsSync(outputPath)) {
          throw new Error(
            `Failed to find the expected output file "${outputPath}" generated by the migration tool.`
          )
        }

        // Use generated config will have FlatCompat, so continue to apply
        // the next steps to it.
        eslintConfigPath = outputPath
        eslintConfigFilename = path.basename(eslintConfigPath)
      } catch (cause) {
        throw new Error(
          `Failed to run "${command}" to migrate the legacy ESLint config "${eslintConfigFilename}".\n` +
            `Please try the migration to Flat config manually.\n` +
            `Learn more: https://eslint.org/docs/latest/use/configure/migration-guide`,
          { cause }
        )
      }
    }

    console.log(`   Found existing ESLint Flat config: ${eslintConfigFilename}`)

    // First try to replace FlatCompat usage if present
    replaceFlatCompatInConfig(eslintConfigPath)

    // Always try to update flat config with Next.js configurations
    // regardless of whether FlatCompat was found
    const updated = updateExistingFlatConfig(eslintConfigPath, isTypeScript)

    if (!updated) {

View on GitHub (pinned to 0ae8c72462)

Solutions

Run `npx @eslint/migrate-config <your-config-file>` manually to see the actual error.
Install @eslint/migrate-config globally or locally and run it directly instead of via npx.
If offline, download the tool or migrate the config by hand following https://eslint.org/docs/latest/use/configure/migration-guide.
Clear npx cache (`npx clear-npx-cache`) and retry.

Example fix

// The codemod runs:
// npx @eslint/migrate-config .eslintrc.json
// If it fails, do it manually:
// npm install -g @eslint/migrate-config
// eslint-migrate-config .eslintrc.json

Defensive patterns

Strategy: try-catch

Validate before calling

import { execSync } from 'child_process'
// Pre-check that @eslint/migrate-config is available
function canRunMigration(): boolean {
  try { execSync('npx @eslint/migrate-config --help', { stdio: 'ignore' }); return true } catch { return false }
}

Try / catch

try {
  execSync(`npx @eslint/migrate-config ${configPath}`, { cwd: projectRoot, stdio: 'pipe' })
} catch (e) {
  // Fall back to manual migration
  console.error('Automatic ESLint config migration failed. Migrate manually.')
}

Prevention

Ensure internet access is available for npx to fetch @eslint/migrate-config.
Validate the legacy ESLint config is syntactically correct before running the codemod.
Pre-install @eslint/migrate-config locally to avoid npx network failures.

When it happens

Trigger: Running the next-lint-to-eslint-cli codemod with an existing legacy ESLint config; the spawned `npx @eslint/migrate-config` command exits non-zero — network failure fetching the package, the tool crashing on an unsupported config format, or npx itself failing.

Common situations: No internet access to fetch @eslint/migrate-config via npx; the legacy ESLint config uses an unsupported format or syntax the migration tool can't parse; an incompatible @eslint/migrate-config version; corrupted npx cache.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/cff6ef233bde5bd1. Report an issue: GitHub.