Biome "Found an unknown key" / Invalid biome.json - Fix in CI

Biome (formatter + linter) is configured via biome.json. It errors when the file has an unknown key, a value of the wrong type, or a schema that does not match the installed Biome version - common when the config and the CLI are on different majors.

What this error means

Running biome ci / biome check exits with Found an unknown key '<key>', Invalid configuration, or a $schema mismatch. It reproduces every run against that config and CLI version.

biome output

biome.json:5:5 Found an unknown key `organizeImports`.
  i Biome v2 moved this option; see the migration guide.
Some errors were emitted while running checks.

Common causes

Config key not valid for the installed Biome

A key was renamed, moved, or removed across Biome majors (e.g. options reorganized in v2). A biome.json written for one major errors on another.

$schema points at a different version

The $schema URL/version in biome.json does not match the installed @biomejs/biome, so validation rejects keys the installed CLI does not know.

How to fix it

Migrate the config to the installed version

Biome ships a migration command that rewrites the config for the current major.

Terminal

npx @biomejs/biome migrate --write
# confirm the installed version
npx @biomejs/biome --version

Align config and CLI versions

Pin @biomejs/biome so CI and local use the same major.
Set $schema to match the installed version.
Remove or rename keys the installed Biome reports as unknown.

How to prevent it

Pin @biomejs/biome and keep biome.json $schema in sync.
Run biome migrate after each major upgrade.
Validate the config in CI with biome ci before relying on it.