Troubleshooting Biome Linting: When Custom Rules Don’t Apply

Problem Statement

After adding or updating biome.config.js (or .biome.json) you run biome check and the expected linting or formatting rules never fire. Instead, Biome reports only the default behavior or silently skips the new rules. This guide walks you through the most common causes, the ordered checks you should perform, and the fixes that resolve each scenario.

Recognizable Condition

• Running biome check . produces no errors for files that should trigger custom rules.
• Verbose output shows the configuration file is loaded, but the rule list is empty or contains unknown entries.
• Changing a rule in the config and rerunning biome check shows the same result.

Cause & Diagnostic Table

Cause	Diagnostic Indicator
Config file not in project root or misnamed	Biome reports default config; --verbose shows "No config file found"
Cache holds stale rule set	Repeated runs give identical results; no change after editing config
Deprecated or renamed rule identifiers	Verbose output lists "Unknown rule: ..." or no rule listed
Biome version older than rule syntax	CLI errors are swallowed; rule definitions are omitted
Incompatible TypeScript compiler settings	TypeScript‑specific rules are skipped; linting stops at TS parsing errors
File ignore patterns override rules	Files are marked as ignored in .biomeignore or --ignore flags

Ordered Checks & Fixes

1. Verify Config Location and Name

   Run:

   biome check . --verbose

   Look for a line such as Using configuration file: /path/to/project/biome.config.js. If it points to the wrong location or the file is missing, move the config to the project root or rename it correctly.

   Typical pitfalls:

   • Using biome.config.ts instead of .js without a transpilation step.
   • Having the file inside a nested config folder.

2. Clear Biome’s Cache

   Biome stores parsed rule sets in an internal cache. After editing the config, clear it with:

   biome cache clear

   Run the check again. If the rules now apply, the issue was stale cache. No state change beyond the cache, so no rollback needed.

3. Check Rule Identifiers

   Open your config and compare rule names against the official rule list. For example, a rule previously called no-console may now be style/no-console in newer Biome releases.

   Run:

   biome check . --verbose

   Any unknown rule names will appear as warnings. Update or remove them. After editing, clear the cache again.

4. Confirm Biome Version Compatibility

   Check the installed binary:

   biome --version

   Compare with the version documented for your config syntax. If you’re using a rule syntax from Biome 1.2 but the CLI reports 1.0, upgrade:

   npm install biome@latest --save-dev

   Re‑run the check to ensure the new version accepts the config.

5. Validate TypeScript Integration

   Biome relies on the TypeScript compiler to parse files when tsconfig.json is present. Run:

   tsc --showConfig

   Verify that compilerOptions such as moduleResolution and target match the expectations in the Biome docs. If the TS compiler reports errors, fix them first; otherwise, Biome may silently skip TS‑specific rules.

6. Inspect Ignore Patterns

   Open .biomeignore (or check flags passed to biome check). Ensure that the files you expect to lint are not listed. Remember that ignore patterns take precedence over rule application.

   Example snippet:

   # ignore all test files
   **/*.test.ts
   

   Remove or adjust the pattern, then rerun the check.

Concrete Example

Suppose you added a rule to enforce no console statements:

// biome.config.js
module.exports = {
  linter: {
    rules: {
      'style/no-console': 'error'
    }
  }
};

After running biome check ., you see no errors. Follow the steps above. In this case:

• The config was actually named biome.config.ts, so Biome used the default config.
• After moving it to biome.config.js and clearing the cache, the console statements are flagged.

Escalation Criteria

• If all checks above pass and the rules still don’t apply, verify the rule set is enabled for the file types you’re linting (e.g., ts vs js).
• Check for global Biome configuration files (e.g., ~/.biome.json) that might override project settings.
• Consult the Biome issue tracker for similar bugs, especially around new releases.
• If you suspect a binary corruption, reinstall Biome or use the --no-cache flag to force a fresh parse.

Limitations & Practical Verification

• Biome’s CLI may swallow syntax errors in older releases; always run --verbose to surface hidden warnings.
• Cache clearing commands differ between shells; if biome cache clear fails, delete the ~/.cache/biome directory manually.
• When adjusting tsconfig.json, remember that Biome respects include and exclude fields; a mis‑configured exclude can hide files from linting.

By systematically applying the ordered checks above, you can pinpoint why Biome isn’t applying your custom rules and restore consistent linting behavior across your codebase.