Biome Diagnostic Guide: Spotting and Fixing Common `biome check` Failures

Recognizable Condition

Running biome check (or biome lint) in a repository that otherwise passes locally but fails in CI, or when the tool exits non‑zero with a message like "files were not processed", is the most common symptom. It usually indicates that Biome is not analyzing the files you expect.

Common Causes & Quick Diagnostic Table

Condition	Typical Cause	Diagnostic Step	Fix
Zero files processed	Biome’s vcs.useIgnoreFile enabled and .gitignore or .biomeignore excludes all target files.	biome check --verbose – look for the "ignored by VCS" section.	Adjust ignore patterns or disable vcs.useIgnoreFile for the run.
Non‑zero exit but files exist	Biome cannot find a biome.json in the current directory or any ancestor.	biome check --config-path ./path/to/biome.json to force a config.	Run from the project root or add a biome.json at the root.
Schema or version mismatch	Config file written for a different major version of Biome.	Check biome.json’s $schema URL and compare to biome --version.	Run biome migrate or update the config to match the installed version.
Parser errors block linting	File contains syntax not supported by the parser (e.g., JSX in a .js file).	Run biome check --verbose – parser errors appear first.	Rename the file to .jsx or add the appropriate language pragma.
Oscillating diffs in CI	Formatter output conflicts with another tool (Prettier, editor format‑on‑save).	Run biome check --format locally and compare to the CI diff.	Disable the competing formatter or align options (e.g., indentSize, lineWidth).
Local pass, CI fail	Version mismatch between the globally installed Biome binary and the one pinned in the repo.	Print biome --version locally and in CI, then check package-lock.json or pnpm-lock.yaml.	Pin @biomejs/biome in devDependencies and run via npx biome … or yarn biome ….

Ordered Checks & Fixes

1. Verify the Working Directory
   • Run pwd (Linux/macOS) or cd (Windows) to ensure you’re in the project root where biome.json lives.
   • If you’re in a sub‑folder of a monorepo, either run from the root or use --config-path.
2. Inspect Ignored Files
   • Execute biome check --verbose.
   • Look for a section like Ignored by VCS: 12 files. If the files you expect are listed, adjust .gitignore or .biomeignore.
   • To test, temporarily disable VCS ignore: biome check --no-vcs-use-ignore-file.
3. Confirm Config Discovery
   • Run biome check --config-path ./biome.json.
   • Check the output for Using config file: /full/path/to/biome.json.
   • If it reports “No config found”, add a biome.json to the root.
4. Validate Schema / Version Alignment
   • Open biome.json and inspect the $schema field. It should point to the JSON schema for the installed version, e.g., https://biomejs.dev/schema/v1.json.
   • Run biome --version to see the binary’s major version.
   • If they differ, run biome migrate which rewrites the config to the current schema.
5. Check for Parser Diagnostics
   • Parser errors appear before any lint rules. Run biome check --verbose and look for lines like Failed to parse file ….
   • Common triggers:
     • Using TSX syntax in a .js file.
     • Missing import type in a .ts file that uses type-only imports.
     • Using a language feature (e.g., optional chaining) not yet supported by the parser.
   • Fix by adjusting file extensions, adding // @ts-check pragmas, or updating the file to valid syntax.
6. Resolve Formatter Conflicts
   • Run biome check --format locally and compare the diff to the CI output.
   • If the diffs differ, either disable the other formatter or set formatter options in biome.json to match.
   • Example:

     {"formatter":{"indentSize":2,"lineWidth":80,"quoteStyle":"single"}}

7. Pin Biome Version in CI
   • Add @biomejs/biome to devDependencies.
   • In your CI script, use npx biome check or yarn biome check to run the pinned binary.
   • Verify by printing biome --version in the CI log.

Escalation Criteria

If all of the above checks pass and you still see failures, consider the following:

• Run biome check --verbose and capture the output. Look for error codes or messages that reference internal Biome modules.
• Reduce the project to a minimal repository containing only the problematic file(s). If the issue persists, it is likely a bug in Biome rather than a configuration problem.
• Search the Biome issue tracker or Discord channel for similar reports. If none exist, file a new issue with the minimal reproduction, the output from biome rage (if available), and your environment details.

Practical Verification Checklist

• Confirm config path: biome check --config-path ./biome.json → should show “Using config file” line.
• Verify ignore behavior: biome check --verbose → list of ignored files matches expectation.
• Check parser errors: biome check --verbose → no “Failed to parse” lines for the target files.
• Validate CI version: biome --version in CI → matches package-lock.json entry.

By following this ordered diagnostic path, you can quickly isolate the root cause of most Biome failures and apply the appropriate fix, ensuring consistent linting and formatting across local development and continuous integration environments.