Blocks are nested too deeply ({num}). Maximum allowed is {ma

Error message

Blocks are nested too deeply ({num}). Maximum allowed is {max}.

What it means

Emitted by the `max-depth` rule when nested blocks (if/else, loops, try, plain blocks — but not function boundaries) exceed the configured nesting depth; oxc's default `DEFAULT_MAX_DEPTH = 4` (crates/oxc_linter/src/rules/eslint/max_depth.rs:24). Each level of `{}` nesting inside a function body increments the depth; the diagnostic reports the actual depth and the allowed maximum on the offending block's span.

Source

Thrown at crates/oxc_linter/src/rules/eslint/max_depth.rs:15

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_semantic::AstNodes;
use oxc_span::GetSpan;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::Value;

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

fn max_depth_diagnostic(num: u32, max: u32, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!("Blocks are nested too deeply ({num}). Maximum allowed is {max}."))
        .with_help("Consider refactoring your code.")
        .with_label(span)
}

const DEFAULT_MAX_DEPTH: u32 = 4;

#[derive(Debug, Clone, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct MaxDepth {
    /// The `max` enforces a maximum depth that blocks can be nested
    max: u32,
}

impl Default for MaxDepth {
    fn default() -> Self {
        Self { max: DEFAULT_MAX_DEPTH }
    }
}

View on GitHub (pinned to e1e7af627c)

Solutions

Extract inner blocks into well-named helper functions or predicates (`isValidOrder(user, order)`) to flatten the nesting.
Invert conditionals and return early (guard clauses) to remove whole nesting levels.
Raise `max` in config (e.g. `{ "max-depth": ["error", 6] }`) if the domain genuinely needs deeper nesting and extraction hurts readability.

Example fix

// before
if (user) {
  if (user.active) {
    if (user.orders) {
      if (user.orders.length) {
        process(user.orders);
      }
    }
  }
}

// after
if (!user?.active?.orders?.length) return;
process(user.orders);

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast in CI: oxlint --rule max-depth=4 src/
// Tighten over time: 4 -> 3 once the worst offenders are refactored.

Prevention

Prefer guard clauses (early return) over wrapping another if-layer; it removes a nesting level each time.
Extract predicate helpers (`isEligible(user)`) so compound conditions collapse into one level.
Configure your editor to indent-guide/rainbow brackets so deep nesting is visible while typing, before lint catches it.

When it happens

Trigger: Write five or more levels of nested control flow in one function, e.g. `if (a) { for (...) { if (b) { while (...) { if (c) { ... } } } } }` — the fifth block triggers with default max 4. Function nodes do not add depth (is_function_node resets the count), so nesting inside callbacks starts fresh.

Common situations: Callback-heavy legacy code with layered conditionals; deeply nested validation ladders; porting an ESLint config with a stricter `max` (2 or 3) onto existing code; new contributors adding one more guard clause to already-deep code and tripping the limit.

Related errors

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