eslint/eslint · error · IncompatibleKeyError

This appears to be in eslintrc format rather than flat confi

Error message

This appears to be in eslintrc format rather than flat config format.

What it means

Thrown as IncompatibleKeyError by createEslintrcErrorSchema for any eslintrc-only key that appears in a flat config. The blocked keys are listed in eslintrcKeys: env, extends, globals, ignorePatterns, noInlineConfig, overrides, parser, parserOptions, reportUnusedDisableDirectives, root. Flat config has no equivalent for these exact keys and fails fast to surface migration mistakes.

Source

Thrown at lib/config/flat-config-schema.js:549

				assertIsRuleSeverity(ruleId, ruleOptions[0]);
			} else {
				assertIsRuleSeverity(ruleId, ruleOptions);
			}
		}
	},
};

/**
 * Creates a schema that always throws an error. Useful for warning
 * about eslintrc-style keys.
 * @param {string} key The eslintrc key to create a schema for.
 * @returns {ObjectPropertySchema} The schema.
 */
function createEslintrcErrorSchema(key) {
	return {
		merge: "replace",
		validate() {
			throw new IncompatibleKeyError(key);
		},
	};
}

const eslintrcKeys = [
	"env",
	"extends",
	"globals",
	"ignorePatterns",
	"noInlineConfig",
	"overrides",
	"parser",
	"parserOptions",
	"reportUnusedDisableDirectives",
	"root",
];

//-----------------------------------------------------------------------------

View on GitHub (pinned to f131c034ad)

Solutions

Replace extends with importing the recommended config and spreading it into your array.
Move parser to languageOptions.parser and parserOptions to languageOptions.parserOptions.
Move globals into languageOptions.globals and convert overrides into additional flat config objects with files globs.

Example fix

// before
module.exports = { extends: ["eslint:recommended"], parser: "@babel/eslint-parser" };
// after
const recommended = require("eslint").config.recommended;
module.exports = [
  ...recommended,
  { languageOptions: { parser: require("@babel/eslint-parser") } }
];

Defensive patterns

Strategy: validation

Validate before calling

const ESLINTRC_KEYS = new Set(['env','extends','globals','ignorePatterns','noInlineConfig','overrides','parser','parserOptions','reportUnusedDisableDirectives','root']);
function hasEslintrcKeys(config) {
  return Object.keys(config).some(k => ESLINTRC_KEYS.has(k));
}

Type guard

function isFlatConfig(c) {
  const bad = ['env','extends','globals','ignorePatterns','noInlineConfig','overrides','parser','parserOptions','reportUnusedDisableDirectives','root'];
  return !bad.some(k => k in c);
}

Try / catch

try { /* load */ } catch (e) { if (e.messageTemplate === 'eslintrc-incompat') console.error('Remove eslintrc key', e.messageData.key); else throw e; }

Prevention

Run the migration tool when moving from eslintrc to flat config.
Grep new configs for extends/parser/overrides before committing.
Keep a checklist of converted keys during migration.

When it happens

Trigger: An eslint.config.js containing extends: ["eslint:recommended"], parser: "@babel/eslint-parser", or overrides: [...]. createEslintrcErrorSchema(key).validate always throws.

Common situations: Renaming .eslintrc.json to eslint.config.js without converting the structure; copy-pasting snippets from old tutorials; using a shareable config that still exports eslintrc shape.

Related errors

AI-assisted analysis of eslint/eslint@f131c034ad (2026-08-03). Data as JSON: /data/errors/534a8cfd28df9198.json. Report an issue: GitHub.