Use "@ts-expect-error" instead of @ts-ignore, as "@ts-ignore

Error message

Use "@ts-expect-error" instead of @ts-ignore, as "@ts-ignore" will do nothing if the following line is error-free.

What it means

Second diagnostic of oxlint's ban-ts-comment rule. When `ts-ignore` is configured as `"allow-with-description"` but the comment has no (or too-short) description, this message nudges you to `@ts-expect-error` instead. The reason: @ts-ignore suppresses whatever is on the next line and silently does nothing once that line becomes error-free, while @ts-expect-error turns into a compile error when its suppression becomes stale — fail-loud instead of fail-silent.

Source

Thrown at crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs:24

use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    context::{ContextHost, LintContext},
    rule::{DefaultRuleConfig, Rule},
    utils::deserialize_required_regex_option,
};

fn comment(ts_comment_name: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!(
        "Do not use @ts-{ts_comment_name} because it alters compilation errors."
    ))
    .with_help(format!("Remove the @ts-{ts_comment_name} directive and fix the underlying TypeScript error instead. If you must suppress an error, consider using @ts-expect-error with a descriptive comment explaining why it's necessary."))
    .with_label(span)
}

fn ignore_instead_of_expect_error(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Use \"@ts-expect-error\" instead of @ts-ignore, as \"@ts-ignore\" will do nothing if the following line is error-free.")
        .with_help("Replace \"@ts-ignore\" with \"@ts-expect-error\".")
        .with_label(span)
}

fn comment_requires_description(ts_comment_name: &str, min_len: u64, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!(
        "Include a description after the @ts-{ts_comment_name} directive to explain why the @ts-{ts_comment_name} is necessary. The description must be {min_len} characters or longer."
    ))
    .with_help(format!("Add a description after @ts-{ts_comment_name} that is at least {min_len} characters long, explaining why the directive is necessary. For example: `// @ts-{ts_comment_name}: TS2345 - This is a known limitation with third-party types`"))
    .with_note("Requiring descriptions ensures that developers document why they're suppressing TypeScript errors, making it easier for future maintainers to understand the context and decide if the suppression is still necessary.")
    .with_label(span)
}

fn comment_description_not_match_pattern(
    ts_comment_name: &str,
    pattern: &str,
    span: Span,
) -> OxcDiagnostic {

View on GitHub (pinned to e1e7af627c)

Solutions

Replace `// @ts-ignore` with `// @ts-expect-error: <reason ≥ minimumDescriptionLength chars>`.
Verify the next line still has an error after switching — @ts-expect-error fails compilation if it does not (which is the point).
Better: fix the underlying error and remove the directive entirely.
If a regex governs the description shape (descriptionFormat), match it, e.g. `: TS2345 because <reason>`.

Example fix

// before
// @ts-ignore
legacyAssign(target, source);

// after
// @ts-expect-error: TS2345 - third-party types lack the v2 field until the next release
legacyAssign(target, source);

Defensive patterns

Strategy: validation

Validate before calling

oxlint --ts-plugin src/ # with { "ts-ignore": "allow-with-description" } configured

Prevention

Prefer @ts-expect-error over @ts-ignore everywhere — stale suppressions then fail the build instead of rotting.
Write descriptions that name the error code and reason (e.g. 'TS2345 - vendor types lack field X').
Raise minimumDescriptionLength if one-word descriptions keep slipping through.

When it happens

Trigger: Config contains `{ "ts-ignore": "allow-with-description" }` (or a descriptionFormat variant) and source has a bare `// @ts-ignore` with no trailing description, or one shorter than minimumDescriptionLength (default 3). The default configuration never produces this message (default ts-ignore is simply banned → the generic 'Do not use' diagnostic).

Common situations: Teams that softened the ban to allow-with-description to unblock a migration and still write naked @ts-ignore; long-lived suppressions nobody dares delete; code review wants a reason on every suppression line.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/cb0b8ac912eb7a95. Report an issue: GitHub.