oxc-project/oxc · warning · OxcDiagnostic

Missing JSDoc `@throws` description.

Error message

Missing JSDoc `@throws` description.

What it means

This is the oxlint `jsdoc/require-throws-description` diagnostic. It fires when a function's JSDoc has a `@throws` tag with no description text. The point of `@throws` is to tell callers what failure occurred, so a bare `@throws {Error}` conveys nothing actionable.

Source

Thrown at crates/oxc_linter/src/rules/jsdoc/require_throws_description.rs:12

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    context::LintContext,
    rule::Rule,
    utils::{should_ignore_as_internal, should_ignore_as_private},
};

fn require_throws_description_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing JSDoc `@throws` description.")
        .with_help("Add description comment to `@throws` tag.")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct RequireThrowsDescription;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Requires a description for `@throws` tags.
    ///
    /// ### Why is this bad?
    ///
    /// A `@throws` tag should explain the condition or reason an error may be thrown.
    ///
    /// ### Examples
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Describe the failure condition: `@throws {TypeError} When `id` is not a string.`
2. Exempt internal helpers with `@private`/`@internal` when their docs are not user-facing.
3. Turn the rule off if your team documents exceptions in prose instead (`"jsdoc/require-throws-description": "off"`).

Example fix

// before
/**
 * @throws {RangeError}
 */
function parsePort(input) {}

// after
/**
 * @throws {RangeError} When `input` is not between 0 and 65535.
 */
function parsePort(input) {}

// Flag @throws tags with no description (type-only or bare)
const src = require('fs').readFileSync(file, 'utf8');
const bare = /@throws(?:\s+\{[^}]*\})?\s*$/m.exec(src);
if (bare) console.error('jsdoc/require-throws-description will fire:', file);

When it happens

Trigger: A function's attached JSDoc contains `@throws {TypeError}` or bare `@throws` with empty comment text after the tag/type. The block is not exempted via `@private`/`@internal` or JSDoc settings.

Common situations: Enabling stricter jsdoc rules over legacy doc comments that list exception types only; bulk-enabling `jsdoc/*` rules in `.oxlintrc.json` during an ESLint-to-oxlint migration.

Related errors

• Invalid access level is specified or missing.
• Missing JSDoc `@returns` description.
• Missing JSDoc `@returns` type.
• Missing JSDoc `@throws` type.
• Missing JSDoc `@yields` declaration for generator function.

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