oxc-project/oxc · warning · OxcDiagnostic

Prefer `catch` to `then(a, b)` or `then(null, b)`

Error message

Prefer `catch` to `then(a, b)` or `then(null, b)`

What it means

Diagnostic from the oxlint rule `promise/prefer-catch` (plugin `promise`). It flags the two-argument error-handler form of `then`: `then(a, b)` and `then(null, b)`. The second argument only handles rejections from upstream - it does NOT catch errors thrown inside the success handler `a` - whereas a chained `.catch()` handles both. This asymmetry is the reason the pattern is considered an anti-pattern.

Source

Thrown at crates/oxc_linter/src/rules/promise/prefer_catch.rs:9

use oxc_ast::{AstKind, ast::Expression};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{AstNode, context::LintContext, rule::Rule};

fn prefer_catch_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prefer `catch` to `then(a, b)` or `then(null, b)`")
        .with_help(
            "Handle promise errors in a `catch` instead of using the second argument of `then`.",
        )
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prefer `catch` to `then(a, b)` and `then(null, b)`. This rule disallows the passing of an
    /// argument into the second parameter of `then` calls for handling promise errors.
    ///
    /// ### Why is this bad?
    ///
    /// A `then` call with two arguments can make it more difficult to recognize that a catch error

View on GitHub (pinned to e1e7af627c)

Solutions

1. Split the handlers: `p.then(onSuccess).catch(onFailure)`
2. If `onFailure` really must only cover upstream rejections, document it and suppress the rule inline

Example fix

// before
p.then(render, showError)

// after
p.then(render).catch(showError)

npx oxlint --promise/prefer-catch src/

When it happens

Trigger: `p.then(onSuccess, onFailure)`; `p.then(null, onFailure)` used as a catch substitute.

Common situations: Code ported from other promise libraries where the pair form was idiomatic; authors avoiding a second chain link for brevity; older tutorials.

Related errors

• Expected throw instead of Promise.reject
• Promise executor functions should not be `async`.
• Unexpected `await` inside a loop.
• Avoid nesting promises.
• Do not use `new` on `Promise.{static_name}`

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