Limits of recovering from a failed ESLint Flat Config upgrade

Question

Goal: Revert to legacy configuration after a Flat Config failure
When upgrading to the Flat Config system in ESLint 8+, a mis‑configured eslint.config.js can cause linting to fail or produce incorrect results. The project may still rely on a working legacy .eslintrc hierarchy, but the presence of the new file overrides it. The goal is to recover the previous state without manual rewrites or loss of plugin compatibility.
Constraints include: the project has already been built with the new config, some plugins are imported as objects, and the legacy config uses string references. There is no built‑in “undo” command in ESLint, and the migration is a breaking change that may affect CI pipelines.
Questions:

Can ESLint automatically detect a failed eslint.config.js and fall back to the legacy .eslintrc hierarchy?
Is there a CLI flag or environment variable that toggles between Flat Config and legacy mode at runtime?
What minimal changes are required to restore the legacy configuration after a failed upgrade, while preserving plugin functionality?

Tasadduq Burney · Answer

Can ESLint automatically fall back to legacy config?
No. When eslint.config.js is present and it throws an error, ESLint stops with a fatal message and does not try the legacy .eslintrc hierarchy. The tool treats the presence of a flat config file as a signal to use only that source.
Is there a CLI flag or environment variable to toggle modes?
ESLint does not expose a dedicated --legacy flag. However, two mechanisms let you force legacy parsing:

--config <file> – Point explicitly to a legacy .eslintrc.* file. This bypasses any eslint.config.js that may exist.
Environment variable ESLINT_USE_FLAT_CONFIG=0 – Setting it to 0 disables flat‑config parsing entirely, making ESLint fall back to the traditional hierarchy even if a flat file is present.

Minimal steps to restore legacy configuration

Backup the flat file (optional). mv eslint.config.js eslint.config.js.bak
Set the environment variable. In a shell session:
export ESLINT_USE_FLAT_CONFIG=0

Or add it to your CI job definition.
Verify the legacy config is being used. Run:
npx eslint --print-config src/index.js | grep "extends" | head

The output should list the legacy .eslintrc files, not eslint.config.js.
Ensure plugins referenced by string names are installed. If the legacy config uses "plugin:react/recommended", confirm eslint-plugin-react is in devDependencies. No changes are needed to the plugin import syntax.
Test a lint run. npx eslint src/**/*.js should exit with 0 and report no configuration errors.

After these steps, CI pipelines that previously failed due to the broken flat config will resume using the legacy hierarchy without any manual rewrites. If you later wish to re‑enable flat config, simply restore eslint.config.js and unset the environment variable.

Limits of recovering from a failed ESLint Flat Config upgrade

Goal: Revert to legacy configuration after a Flat Config failure

1 answer

Can ESLint automatically fall back to legacy config?

Is there a CLI flag or environment variable to toggle modes?

Minimal steps to restore legacy configuration

Your perspective belongs here.

0 question comments