oxc-project/oxc · warning

Do not use @ts-{ts_comment_name} because it alters compilati

Error message

Do not use @ts-{ts_comment_name} because it alters compilation errors.

What it means

Diagnostic from oxlint's port of @typescript-eslint/ban-ts-comment. Compiler-directive comments that suppress TypeScript errors (`@ts-ignore`, `@ts-nocheck` by default) silently mask real type problems, so the rule bans them and tells you to fix the underlying error. Defaults: ts-ignore and ts-nocheck banned, ts-expect-error allowed only with a description (minimumDescriptionLength 3), ts-check allowed. This base 'Do not use @ts-X' message is the banned-directive diagnostic.

Source

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

use cow_utils::CowUtils;
use lazy_regex::Regex;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
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.")

View on GitHub (pinned to e1e7af627c)

Solutions

1. Fix the underlying type error and delete the directive (the only real fix).
2. If suppression is legitimate and temporary, switch to `// @ts-expect-error: <why>` — it errors out once the underlying error disappears, unlike @ts-ignore.
3. Configure per-directive policy instead of banning: e.g. `{ "ts-ignore": "allow-with-description", "ts-nocheck": false }` with a minimumDescriptionLength.
4. For whole-file legacy opts, scope an inline disable comment narrowly rather than disabling the rule repo-wide.

Example fix

// before
// @ts-ignore
const total: number = "42";

// after
const total: number = 42;
// or, when suppression is justified:
// @ts-expect-error: legacy payload types are wrong until v2
const total: number = readLegacy();

oxlint --ts-plugin src/ # ban-ts-comment defaults: ts-ignore/ts-nocheck banned

# measure suppression debt before cleanup
rg -n --no-ignore '@ts-(ignore|nocheck)' src/ | wc -l

When it happens

Trigger: A `// @ts-ignore` or `// @ts-nocheck` comment when the directive's config is true (banned) — both are banned out of the box; also any directive configured `true` that appears in code. (A description-less `@ts-expect-error` under its allow-with-description default produces the sibling comment_requires_description diagnostic instead; missing-description `@ts-ignore` under allow-with-description produces the ignore_instead_of_expect_error diagnostic.)

Common situations: Suppressing noisy third-party typing issues and never revisiting; migrating JS→TS files sprinkled with @ts-ignore; bulk `@ts-nocheck` on legacy files to get CI green; upgrading TypeScript versions that surface new errors.

Related errors

• Use "@ts-expect-error" instead of @ts-ignore, as "@ts-ignore
• Include a description after the @ts-{ts_comment_name} direct
• encountered allocation error
• Expected error to be handled.
• Type can be trivially inferred from the initializer

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