oxc-project/oxc · warning · OxcDiagnostic

Don't return in a finally callback

Error message

Don't return in a finally callback

What it means

Diagnostic from the oxlint rule `promise/no-return-in-finally` (plugin `promise`). It flags any `return` statement inside the callback of a `.finally()` (member call recognized by `is_promise`). A finally callback cannot alter the settled outcome of the chain: the returned value is discarded, so the return is dead code that misleads readers into thinking something consumes it.

Source

Thrown at crates/oxc_linter/src/rules/promise/no_return_in_finally.rs:12

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

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

fn no_return_in_finally_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Don't return in a finally callback")
        .with_help("Remove the return statement as nothing can consume the return value")
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Disallow return statements in a `finally()` callback of a promise.
    ///
    /// ### Why is this bad?
    ///
    /// Disallow return statements inside a callback passed to finally(), since nothing would
    /// consume what's returned.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

1. Remove the `return` so the callback only performs side effects
2. Use a block body for arrow callbacks: `p.finally(() => { cleanup() })` instead of `p.finally(() => cleanup())`
3. If you need the value afterwards, move the logic to a `.then()` before the `.finally()`

Example fix

// before
p.finally(() => {
  return cleanup()
})

// after
p.finally(() => {
  cleanup()
})

npx oxlint --promise/no-return-in-finally src/

When it happens

Trigger: `p.finally(() => { return cleanup() })`; `p.finally(function () { return; })` inside a promise chain.

Common situations: Cleanup callbacks written by habit with implicit or explicit returns; converting synchronous `try/finally` helpers into `.finally()`; arrow functions whose body is a single expression (implicit return).

Related errors

• Avoid nesting promises.
• Avoid wrapping return values in Promise.resolve
• Prefer await to then()/catch()/finally()
• Promise executor functions should not be `async`.
• Unexpected `await` inside a loop.

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