oxc-project/oxc · warning

Expected error to be handled.

Error message

Expected error to be handled.

What it means

Diagnostic from oxlint's port of ESLint's node/handle-callback-err rule. Node's callback convention passes an Error (or null) as the first argument; this rule reports functions whose first parameter matches the configured error name (default "err"; a string starting with `^` is parsed as a regex) but whose body never references it. Unread `err` means failures vanish silently and the success path runs on undefined data.

Source

Thrown at crates/oxc_linter/src/rules/node/handle_callback_err.rs:19

use std::borrow::Cow;

use lazy_regex::Regex;
use schemars::JsonSchema;
use serde::{Deserialize, de::Error as _};

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

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

fn handle_callback_err_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Expected error to be handled.")
        .with_help("Handle the error or rename the parameter if it's not an error.")
        .with_label(span)
}

#[derive(Debug, Clone, JsonSchema)]
enum ErrorPattern {
    Plain(String),
    Regex(Regex),
}

impl Default for ErrorPattern {
    fn default() -> Self {
        Self::Plain("err".to_string())
    }
}

impl ErrorPattern {
    fn matches(&self, name: &str) -> bool {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Handle the error first: `if (err) { ... return; }` (or rethrow) before using the other arguments.
2. If the first parameter is not actually an error, rename it so it does not match the pattern.
3. Configure the pattern to your team's names: `["error", "^(err|error)$"]` (leading ^ marks regex).
4. Suppress inline for a deliberate one-off, e.g. `// oxlint-disable-next-line handle-callback-err`.

Example fix

// before
function loadData(err, data) {
  doSomething(data);
}

// after
function loadData(err, data) {
  if (err) throw err;
  doSomething(data);
}

// pattern matches your team's error-parameter names (leading ^ = regex)
// .oxlintrc.json: "node/handle-callback-err": ["error", "^(err|error)$"]

// the code shape the rule demands, applied preemptively
function loadData(err: Error | null, data?: Buffer) {
  if (err) throw err;
  // safe success path
}

When it happens

Trigger: A function or arrow function whose first FormalParameter is a binding identifier matching the configured pattern (default exactly `err`) with no usage of that identifier in the body: `function loadData(err, data) { doSomething(data); }`, `(err, rows) => render(rows)`. Configure e.g. `"handle-callback-err": ["error", "^(err|error)$"]` to match other names.

Common situations: Legacy Node callback-style code (fs, database drivers, Express middleware); a team naming the parameter `error` while the config stays at default `err` (false negatives) or vice versa (false positives on non-error params named err); refactors that deleted the error branch but kept the signature.

Related errors

• Prefer `async`/`await` to the callback pattern
• Do not use @ts-{ts_comment_name} because it alters compilati
• Disallowed usage of `process.env`.
• Expected throw instead of Promise.reject
• Prefer `catch` to `then(a, b)` or `then(null, b)`

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