oxc-project/oxc · warning · OxcDiagnostic

The description for the @ts-{ts_comment_name} directive must

Error message

The description for the @ts-{ts_comment_name} directive must match the {pattern} format.

What it means

Warning from typescript/ban-ts-comment via comment_description_not_match_pattern() (crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs:43). When the option description-must-match-pattern (a regex) is configured, the description after a @ts-* directive must match that pattern; this fires when it does not. It mirrors @typescript-eslint/ban-ts-comment's descriptionMustMatchPattern.

Source

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

        .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)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct BanTsComment(Box<BanTsCommentConfig>);

#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case", default, deny_unknown_fields)]
/// This rule allows you to specify how different TypeScript directive comments
/// should be handled.
///
/// For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
/// - `true`: Disallow the directive entirely, preventing its use in the entire codebase.
/// - `false`: Allow the directive without any restrictions.
/// - `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rewrite the description to satisfy the pattern, e.g. '// @ts-expect-error: TS2339 - property added in next API version'
2. Check the regex in the JSON config: JSON consumes one backslash layer, so '\d' must be written '\\d'
3. Loosen the pattern (e.g. drop the anchoring or length parts) if it rejects valid descriptions
4. Remove 'description-must-match-pattern' and keep only a length requirement

Example fix

// before (pattern: "^TS\d+: .{10,}")
// @ts-ignore: legacy

// after
// @ts-ignore: TS2345 - union return type from SDK v2, fixed in v3

const PATTERN = new RegExp(config.descriptionMustMatchPattern); // e.g. /^TS\d+: .{10,}$/
const DESCRIBED = /@ts-(ignore|expect-error|nocheck|check):\s*(.*)$/;
for (const line of source.split('\n')) {
  const m = DESCRIBED.exec(line);
  if (m && !PATTERN.test(m[1].trim())) fail('description fails pattern', line);
}

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

When it happens

Trigger: Config such as 'ban-ts-comment: [error, { description-must-match-pattern: "^TS\\d+: .+" }]' combined with a comment like '// @ts-ignore: legacy reason' whose description fails the regex; the offending pattern string is interpolated into the message.

Common situations: Teams enforcing a 'TS error code - reason' convention for suppressions; copying a JS-regex from an .eslintrc into .oxlintrc.json where backslashes need double escaping, so the pattern behaves differently than intended.

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
• Do not use @ts-{ts_comment_name} because it alters compilati
• Type can be trivially inferred from the initializer

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