Diagnosing Persistent Import Order Failures in Biome

The Problem: Import Order Errors That Won't Go Away

You run biome lint and every import statement flags an order violation. You adjust the importOrder pattern in biome.json, rerun, and the same errors persist. Or worse: the errors appear in CI but not locally, or in your IDE but not the CLI. This guide walks through a systematic diagnosis—identifying the recognizable condition, narrowing the cause with a decision table, running ordered checks, applying targeted fixes, and knowing when to escalate.

Recognizable Condition

You're seeing one or more of these symptoms:

• Lint errors on every import statement, even after correcting the importOrder regex.
• Errors differ between biome lint (CLI), your IDE extension, and CI pipeline.
• Running biome cache clear temporarily changes the error set.
• A subdirectory's .biomeignore or nested config makes the same file lint differently depending on working directory.

Useful takeaway: Import order failures in Biome are rarely about the regex alone. They usually stem from config precedence, stale cache, or binary version mismatches. Follow the checks in order; each step either confirms a cause or eliminates it.

Cause & Diagnostic Decision Table

Observed Symptom	Most Likely Cause	Quick Verification
All imports flagged, pattern looks correct	Config not loaded (malformed JSON/YAML) or wrong file read	biome lint --config ./biome.json shows config path
Errors differ between CLI and IDE	IDE uses different Biome binary or config path	Check IDE extension settings; run biome --version in both
Errors disappear after biome cache clear	Stale incremental cache	Re-run lint; if errors return, cache invalidation is incomplete
Subdirectory files lint differently	Local override (.biomeignore, nested config)	find . -name '.biome*' -o -name 'biome*.json' -o -name 'biome*.yaml'
Pattern change has no effect	Regex syntax error (silently ignored)	Validate regex with node -e "console.log(new RegExp('your-pattern').test('test'))"
Rule silently disabled in some files	Inline /* biome-ignore ... */ comments	grep -r 'biome-ignore' --include='*.ts' --include='*.js' .
CI fails, local passes	Different Biome version or config resolution in CI	Compare biome --version and config path in CI logs

Ordered Diagnostic Checks

Run these in sequence. Stop when you identify the root cause.

1. Verify Config Is Loaded and Valid

# Run from project root
biome lint --config ./biome.json 2>&1 | head -20

Expected: Output shows Using config file: ./biome.json (or similar). If you see No configuration file found or a JSON parse error, the config is malformed or not discovered.

Risk: None—read-only.

2. Inspect the Active importOrder Pattern

cat biome.json | jq '.linter.rules.imports.importOrder'
# or for YAML
yq '.linter.rules.imports.importOrder' biome.yaml

Confirm the pattern matches your intended grouping. Example of a valid pattern for grouping external, internal, and relative imports:

{
  "linter": {
    "rules": {
      "imports": {
        "importOrder": {
          "level": "error",
          "options": {
            "groups": [
              ["^@?\\w"],           // external packages
              ["^@/"],               // internal aliases
              ["^\\.\\./", "^\\./"] // relative
            ]
          }
        }
      }
    }
  }
}

Check: Regex anchors (^) and escaped backslashes. A missing anchor or wrong character class makes Biome treat the pattern as a no-op without warning.

3. Search for Conflicting Config Files

find . -type f \( -name 'biome.json' -o -name 'biome.yaml' -o -name '.biomeignore' -o -name '.biomeconfig' \) ! -path '*/node_modules/*'

Multiple configs create precedence conflicts. Biome loads the nearest config to the file being linted. A biome.yaml in a subdirectory overrides root settings for files under that directory.

4. Clear Cache and Restart Daemon

biome cache clear
# If using the daemon (default in watch mode)
biome stop

Re-run lint. If errors change, stale cache was a factor. Note: biome cache clear is safe; it only removes ~/.cache/biome (or project-local .biome/cache).

5. Check for Inline Ignore Comments

grep -rn 'biome-ignore.*import' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' .

These comments disable rules per-file or per-line. They persist across config changes and cause silent violations when the rule is re-enabled.

6. Validate Regex Syntax Independently

# Test each group pattern against sample imports
node -e "
const patterns = ['^@?\\w', '^@/', '^\\.\\./', '^\\./'];
const samples = ['react', '@myorg/utils', '@/components/Button', '../utils', './helpers'];
patterns.forEach(p => {
  const re = new RegExp(p);
  console.log('Pattern:', p);
  samples.forEach(s => console.log('  ', s, '=>', re.test(s)));
});
"

If a pattern matches nothing or everything, adjust before updating config.

7. Align Binary Versions Across Environments

# Local
biome --version
# CI (add to pipeline)
echo "Biome version: $(biome --version)"
# IDE: check extension marketplace version vs. CLI

Version mismatches (e.g., 1.8.3 locally vs. 1.7.0 in CI) change default rules and config schema. Pin Biome version in package.json devDependencies and CI cache key.

Fixes Tied to Findings

Finding	Fix	Verification
Malformed config	Fix JSON/YAML syntax; validate with jq empty biome.json or yamllint biome.yaml	biome lint --config ./biome.json loads without error
Regex syntax error	Correct pattern; escape backslashes for JSON (\\. not \.)	Node test above shows expected matches; lint errors reflect new grouping
Conflicting configs	Consolidate to single root config; remove or align nested configs	find command returns only root config
Stale cache	biome cache clear && biome stop; add to CI before_script	Second lint run matches first (no cache-induced drift)
Inline ignores	Remove or scope comments; use // biome-ignore lint/imports/order: if intentional	grep returns no unexpected ignores
Version mismatch	Pin @biomejs/biome version in package.json; update CI cache key	biome --version identical in all environments
IDE uses different binary	Configure IDE extension to use workspace Biome (via biome.path setting or npx biome)	IDE lint output matches CLI

Escalation Criteria

Escalate (open an issue, consult team, or engage Biome maintainers) when:

1. All checks pass but import order errors remain inconsistent across files with identical import structure.
2. biome lint --diagnostic (if available) shows internal rule IDs that don't map to documented rules.
3. Daemon crashes or biome stop fails repeatedly, suggesting a binary or filesystem issue.
4. Config validation passes but Biome reports Configuration error: unknown rule 'imports/order'—indicates version/schema drift not caught by version check.

Before escalating, capture: Biome version, config file content, biome lint --verbose output, and the exact import statements triggering errors.

Limitations & Version Assumptions

• This guide assumes Biome 1.x (tested against 1.8+). The importOrder schema changed in 1.0; older configs need migration.
• Regex behavior follows JavaScript RegExp semantics. Lookbehinds, named groups, or Unicode property escapes may behave differently in older Node versions bundled with Biome.
• Daemon cache location defaults to ~/.cache/biome but can be overridden by BIOME_CACHE_DIR env var.
• IDE extensions (VS Code, JetBrains) may bundle their own Biome binary; the biome.path setting is the reliable override.

Practical Verification Checklist

After applying fixes, confirm resolution with this sequence:

1. biome cache clear && biome stop
2. biome lint --config ./biome.json — zero import order errors
3. biome check --apply — auto-fixes any remaining safe violations (review diff first)
4. Run same lint command in CI pipeline; compare exit codes and error counts
5. Open a previously problematic file in IDE; verify no spurious diagnostics

If all five steps pass, the import order configuration is stable across environments.