oxc-project/oxc · error · OxcDiagnostic

Shadowing of global properties such as `undefined` is not al

Error message

Shadowing of global properties such as `undefined` is not allowed.

What it means

`no-shadow-restricted-names` reports any binding that shadows one of the five restricted names in `PRE_DEFINE_VAR`: `Infinity`, `NaN`, `arguments`, `eval`, `undefined`; with `report_global_this: true` it also reports shadowing `globalThis`. Shadowing `eval` or `arguments` is a hard SyntaxError in strict mode, and shadowing `undefined`/`NaN`/`Infinity` makes reads inside that scope silently return the local value instead of the global. The rule flags declarations, parameters, and catch bindings with these names.

Source

Thrown at crates/oxc_linter/src/rules/eslint/no_shadow_restricted_names.rs:16

use crate::{
    context::LintContext,
    rule::{DefaultRuleConfig, Rule},
};
use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::Value;

const PRE_DEFINE_VAR: [&str; 5] = ["Infinity", "NaN", "arguments", "eval", "undefined"];

fn no_shadow_restricted_names_diagnostic(shadowed_name: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Shadowing of global properties such as `undefined` is not allowed.")
        .with_help(format!("Rename '{shadowed_name}' to avoid shadowing the global property."))
        .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct NoShadowRestrictedNames(Box<NoShadowRestrictedNamesConfig>);

#[derive(Debug, Clone, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct NoShadowRestrictedNamesConfig {
    /// If true, also report shadowing of `globalThis`.
    report_global_this: bool,
}

impl Default for NoShadowRestrictedNamesConfig {
    fn default() -> Self {
        Self { report_global_this: true }
    }

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rename the shadowing binding to anything else — there is no valid reason to keep these names.
2. For `globalThis` specifically, either rename the alias or disable `reportGlobalThis` in the rule config if the shim is intentional.
3. Run `oxlint --fix` is not applicable here; rename manually, then re-run the linter to confirm zero hits.

Example fix

// before
function f() {
  var undefined = false;
  return undefined; // always false, not the global undefined
}

// after
function f() {
  var isReady = false;
  return isReady;
}

# quick textual pre-check for restricted-name shadowing
rg -n '\b(var|let|const|function|class)\s+(undefined|NaN|Infinity|eval)\b|catch\s*\(\s*(undefined|NaN|Infinity|eval)\s*\)' src/

When it happens

Trigger: Writing `var undefined = 5;`, `function f(eval) {}`, `let NaN = compute();`, `catch (arguments) {}`, or (with `reportGlobalThis: true`) `const globalThis = window;`.

Common situations: Copy-pasted legacy code (pre-ES5) declaring `var undefined`; minified or machine-generated code reusing short global names; enabling `reportGlobalThis` after upgrading oxlint and hitting polyfill shims that alias `globalThis`.

Related errors

• Variable or `function` declarations are not allowed in neste
• '{name}' is already a global variable.
• Empty array binding pattern
• Empty object binding pattern
• Expected method{method_name_str} to have this.

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