oxc-project/oxc · info · OxcDiagnostic

Unexpected use of `undefined`

Error message

Unexpected use of `undefined`

What it means

`no-undefined` (stylistic, off by default in ESLint too) flags every use of the identifier `undefined` — comparisons, assignments, arguments. The rule's rationale: `undefined` is a writable global property in old environments and can be shadowed, so `null` or implicit undefined is held to be safer. The diagnostic is the bare message with a label, no help text.

Source

Thrown at crates/oxc_linter/src/rules/eslint/no_undefined.rs:12

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

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

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

fn no_undefined_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Unexpected use of `undefined`").with_label(span)
}

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Disallow the use of `undefined` as an identifier.
    ///
    /// ### Why is this bad?
    ///
    /// Using `undefined` directly can lead to bugs, since it can be shadowed or overwritten in JavaScript.
    /// It's safer and more intentional to use `null` or rely on implicit `undefined` (e.g., missing return) to avoid accidental issues.
    ///
    /// ### Examples
    ///
    /// Examples of **incorrect** code for this rule:
    /// ```javascript
    /// var foo = undefined;
    ///

View on GitHub (pinned to e1e7af627c)

Solutions

1. Prefer `x == null` (matches both null and undefined) or `x === null` where only null is meant.
2. Use `typeof x === 'undefined'` for globals that may not exist (it never throws).
3. If the identifier use is deliberate style, disable the rule in .oxlintrc.json — most modern teams do.

Example fix

// before
if (config === undefined) {
  config = defaults;
}

// after
if (config == null) {
  config = defaults;
}

# find all uses of the identifier before enabling the rule
rg -n '\bundefined\b' src/

When it happens

Trigger: `if (x === undefined)`, `const y = undefined;`, `f(undefined)` — any `IdentifierReference`/binding resolving to the global `undefined` once the rule is enabled in config.

Common situations: Enabling the rule when adopting a strict style guide and getting hundreds of hits in existing code; teams split on `typeof x === 'undefined'` vs `x === undefined` debate; legacy ES5-era codebases that still defensively avoid the identifier.

Related errors

• Expected method{method_name_str} to have this.
• {prefix} {{ after '{keyword}'{condition_if_needed}.
• Enforce default clauses in switch statements to be last
• Expected a function {style}.
• Accessor pair {getter_key} and {setter_key} should be groupe

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