oxc-project/oxc · warning · OxcDiagnostic

Include a description after the @ts-{ts_comment_name} direct

Error message

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.

What it means

Warning emitted by oxlint rule typescript/ban-ts-comment via comment_requires_description() (crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs:30). When the option minimum-description-length is set, every @ts-ignore, @ts-expect-error, @ts-nocheck, or @ts-check directive must be followed by a description of at least min_len characters; this diagnostic fires when the description is missing or too short.

Source

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

    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 {
    OxcDiagnostic::warn(format!(
        "The description for the @ts-{ts_comment_name} directive must match the {pattern} format."
    ))
    .with_help(format!("Update the description after @ts-{ts_comment_name} to match the required pattern: {pattern}."))
    .with_label(span)
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Append a description of at least the configured length, e.g. '// @ts-ignore: TS2345 - SDK returns number|string until v3 ships'
2. Switch to '@ts-expect-error' with the same descriptive comment so the suppression errors out once the underlying problem is fixed
3. Fix the underlying type error and delete the directive entirely
4. If the policy is too strict, lower 'minimum-description-length' or remove it from .oxlintrc.json

Example fix

// before
// @ts-ignore
JSON.parse(raw);

// after
// @ts-ignore: TS2345 - raw is a trusted internal payload, validated at the boundary
JSON.parse(raw);

const BARE = /\/\/\s*@ts-(ignore|expect-error|nocheck|check)\s*$/;
const DESCRIBED = /@ts-(ignore|expect-error|nocheck|check):\s*(.*)$/;
for (const [i, line] of source.split('\n').entries()) {
  if (BARE.test(line) || (DESCRIBED.test(line) && DESCRIBED.exec(line)![1].trim().length < MIN_LEN)) {
    fail(`line ${i + 1}: @ts- directive missing a ${MIN_LEN}+ char description`);
  }
}

function isDirectiveDescribed(comment: string, minLen = 3): boolean {
  const m = comment.match(/@ts-(?:ignore|expect-error|nocheck|check):\s*(.*)$/);
  return m !== null && m[1].trim().length >= minLen;
}

When it happens

Trigger: oxlint runs with ban-ts-comment configured with 'minimum-description-length' (e.g. 3) and the source contains a directive like '// @ts-ignore' or '// @ts-expect-error: x' with no description or one shorter than the configured length; the span labels the directive comment.

Common situations: Enabling the strict/recommended oxlint preset in CI; inheriting legacy suppression comments written before the option was turned on; writing a terse '// @ts-ignore: fix later' that falls under the configured threshold.

Related errors

• Use "@ts-expect-error" instead of @ts-ignore, as "@ts-ignore
• Do not use @ts-{ts_comment_name} because it alters compilati
• The description for the @ts-{ts_comment_name} directive must
• encountered allocation error
• Type can be trivially inferred from the initializer

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