oxc-project/oxc · warning · OxcDiagnostic

Prefer await to then()/catch()/finally()

Error message

Prefer await to then()/catch()/finally()

What it means

Diagnostic from the oxlint rule `promise/prefer-await-to-then` (plugin `promise`, style category). It fires on every `.then()`, `.catch()`, or `.finally()` member call whose receiver the `is_promise_with_context` utility resolves as a promise. The rule takes no configuration: if it is enabled, all chaining syntax is flagged in favor of `async`/`await` with `try`/`catch`.

Source

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

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::Deserialize;

fn prefer_wait_to_then_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prefer await to then()/catch()/finally()")
        .with_help("Use `await` with `try`/`catch` instead of promise chaining for more readable and maintainable async code.")
        .with_label(span)
}

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

#[derive(Debug, Default, Clone, Deserialize)]
pub struct PreferAwaitToThen(PreferAwaitToThenConfig);

impl std::ops::Deref for PreferAwaitToThen {
    type Target = PreferAwaitToThenConfig;

    fn deref(&self) -> &Self::Target {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rewrite the chain as an `async` function with `await` and `try`/`catch`
2. If the codebase intentionally uses chains, disable the rule: `"promise/prefer-await-to-then": "off"`
3. Scope the rule to new directories only (e.g. `src/modern/**`) via config overrides

Example fix

// before
getUser(id)
  .then(render)
  .catch(showError)
  .finally(hideSpinner)

// after
async function load(id) {
  try {
    const user = await getUser(id)
    render(user)
  } catch (err) {
    showError(err)
  } finally {
    hideSpinner()
  }
}

npx oxlint --promise/prefer-await-to-then src/
# chain-based codebase? turn it off in .oxlintrc.json:
#   { "rules": { "promise/prefer-await-to-then": "off" } }

When it happens

Trigger: Any `x.then(fn)`, `x.catch(fn)`, or `x.finally(fn)` in files covered by the rule; enabling the whole `promise` plugin or the `style` category in `.oxlintrc.json` turns this rule on.

Common situations: Enabling `promise` plugin presets wholesale in an oxlint config migration; mixed-style codebases where chains are intentional; teams that standardized on async/await and want chains gone.

Related errors

• Avoid nesting promises.
• Don't return in a finally callback
• Avoid wrapping return values in Promise.resolve
• Async assertions must be awaited.
• Promise executor functions should not be `async`.

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