Managing Unavoidable Lint Errors with Biome Inline Suppressions

CI is red because a linter rule is firing on code you cannot change—perhaps a third-party API response or a legacy test fixture. The useful takeaway is to treat these exceptions as reviewed artifacts rather than hidden configuration toggles. Biome’s inline suppression comments make the reason visible, rule-scoped, and auditable, turning a silent disable into documented technical debt.

The problem with silent disables

In many JS/TS projects, eslint-disable comments accumulate over time. Because these tools often don't alert you when a disable comment is no longer needed, they linger after refactors, creating "blind spots" in your codebase. Biome addresses this by requiring a reason for the suppression and actively flagging unused suppression comments as diagnostics themselves.

How Biome’s suppression comments work

Biome provides two primary mechanisms for silencing diagnostics. Both require the full rule path (e.g., lint/suspicious/noExplicitAny) rather than just the rule name. A bare rule name will not match and the diagnostic will remain active.

Single-line and File-wide suppression

To suppress a diagnostic on the immediate next line, use the biome-ignore syntax:

// biome-ignore lint/<group>/<rule>: <reason>

To suppress a rule for every instance within a single file, place this at the top of the file:

// biome-ignore-all lint/<group>/<rule>: <reason>

The text following the colon is not merely a comment; Biome echoes this reason in CLI and CI output. This allows reviewers to understand the justification for the exception without having to open the source file.

Rule-scoping and stale comment detection

Suppressions are strictly rule-scoped. If a line triggers three different lint errors and you ignore only one, the other two will still block your CI build. This prevents the "blanket silence" common in older linting patterns.

Crucially, Biome detects "stale" suppressions. If you refactor the code so that the rule no longer triggers, Biome will report the biome-ignore comment itself as an error. Note that this check typically requires a full-file analysis; narrow runs (like checking only staged files) may not always surface these stale comments.

Worked example: Handling volatile API shapes

Consider a scenario where you are consuming a payload from an external webhook. The schema is volatile, and using any is a conscious decision to avoid constant type-definition churn for a non-critical internal tool.

// biome-ignore lint/suspicious/noExplicitAny: Third-party API schema is volatile and unverified
const data: any = await fetchExternalData();
console.log(data.untyped_field);

To verify the suppression, run the following command in your project root (requires Biome installed via npm):

npx @biomejs/biome check ./src/path/to/file.ts

Verification checks:

• If the rule path is correct, the noExplicitAny diagnostic disappears.
• If you typo the path (e.g., lint/suspicious/noExplicitAnyy), the original diagnostic reappears, proving the suppression is exact.
• If you change any to a specific interface, Biome will flag the comment as an unused suppression.

Trade-offs and migration limitations

Biome's syntax is intentionally incompatible with ESLint. If you are migrating a repository and running both tools in parallel, you must maintain both eslint-disable and biome-ignore comments until the migration is complete.

Additionally, rule paths are version-sensitive. Because Biome may reorganize rules into different groups across major versions, a suppression that works in version 1.x might stop matching after an upgrade. This requires teams to audit suppressions during major version bumps.

Actionable closing

To prevent your codebase from becoming a collection of ignored warnings, establish a policy that requires a descriptive reason for every suppression. Treat these comments as code: they should be reviewed in Pull Requests and removed as soon as the underlying technical debt is resolved. By leveraging Biome's unused-suppression detection in your CI pipeline, you ensure that your exceptions remain intentional and current.