oxc-project/oxc · warning · OxcDiagnostic

Unexpected '{term}' comment: {display}

Error message

Unexpected '{term}' comment: {display}

What it means

Diagnostic from the `no-warning-comments` rule. The rule (pedantic category) flags comments containing configured terms such as TODO/FIXME/XXX so unfinished work does not ship silently. The message shows the matched term and the comment text truncated to 40 characters (CHAR_LIMIT) with a trailing '...'. Config: `terms` (case-insensitive array), `location` ('start' = after decoration, or 'anywhere'), and `decoration` characters to skip (e.g. `*` in JSDoc).

Source

Thrown at crates/oxc_linter/src/rules/eslint/no_warning_comments.rs:40

    for word in comment.split_whitespace() {
        let tmp = if comment_to_display.is_empty() {
            word.to_string()
        } else {
            format!("{comment_to_display} {word}")
        };

        if tmp.len() <= CHAR_LIMIT {
            comment_to_display = tmp;
        } else {
            truncated = true;
            break;
        }
    }

    let display = if truncated { format!("{comment_to_display}...") } else { comment_to_display };

    OxcDiagnostic::warn(format!("Unexpected '{term}' comment: {display}"))
        .with_help("Remove or rephrase this comment")
        .with_label(span)
}

#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(default, deny_unknown_fields)]
struct NoWarningCommentsConfig {
    /// An array of terms to match. The matching is case-insensitive.
    terms: Vec<String>,
    /// Where to check for the terms.
    location: Location,
    /// An array of characters to ignore at the start of comments when `location` is `"start"`.
    ///
    /// Useful for ignoring common comment decorations like `*` in JSDoc-style comments.
    decoration: FxHashSet<String>,
    /// Compiled matchers built from the user-facing configuration.
    #[serde(skip)]
    #[schemars(skip)]

View on GitHub (pinned to e1e7af627c)

Solutions

1. Do the work or remove the comment if it is stale.
2. Rephrase so the term is not at the matched location (e.g. 'Note: pending implementation').
3. Track the item in your issue tracker instead of the codebase.
4. Tune config: narrow `terms`, set `location: "start"`, or add decorations so benign matches stop firing; use disable comments for intentional TODOs.

Example fix

// before
// TODO: implement retry logic
function fetch() {}

// after
// Retry logic tracked in ISSUE-482
function fetch() {}

const TERMS = ['todo', 'fixme', 'xxx']; // mirror your oxlint config
function hasWarningComment(commentText, location) {
  const t = commentText.toLowerCase();
  return TERMS.some(term => location === 'anywhere' ? t.includes(term) : t.trimStart().startsWith(term));
}

When it happens

Trigger: Any comment matching a configured term at the configured location: `// TODO: implement` with location 'start', or `/* see FIXME below */` with location 'anywhere'. Terms compile to regex patterns; JSDoc-style `* TODO:` matches once `*` is listed in decoration.

Common situations: CI gates that forbid TODOs before release; teams enabling pedantic presets during a release freeze; legacy repos with hundreds of TODOs suddenly failing lint after adopting oxlint.

Related errors

• Found a comment that would permit fallthrough, but case cann
• Unexpected comment inline with code
• Empty array binding pattern
• Empty object binding pattern
• Redundant Boolean call

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