oxc-project/oxc · warning · OxcDiagnostic

Unexpected ' ' comment

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

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…
• Unexpected comment inline with code
• All 'var' declarations must be at the top of the function…
• Async function has no `await` expression.
• Avoid unnecessary use of .

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

Appendix: 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)