apache/hadoop · error · IllegalStateException

Variable substitution depth too large: 20 {}

Error message

Variable substitution depth too large: 20 {}

What it means

Error "Variable substitution depth too large: 20 {}" thrown in apache/hadoop.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/Configuration.java:1207

      if (val == null) {
        return eval; // return literal ${var}: var is unbound
      }

      final int dollar = varBounds[SUB_START_IDX] - "${".length();
      final int afterRightBrace = varBounds[SUB_END_IDX] + "}".length();
      final String refVar = eval.substring(dollar, afterRightBrace);

      // detect self-referential values
      if (val.contains(refVar)) {
        return expr; // return original expression if there is a loop
      }

      // substitute
      eval = eval.substring(0, dollar)
             + val
             + eval.substring(afterRightBrace);
    }
    throw new IllegalStateException("Variable substitution depth too large: " 
                                    + MAX_SUBST + " " + expr);
  }

  /**
   * Get the environment variable value if
   * {@link #restrictSystemProps} does not block this.
   * @param name environment variable name.
   * @return the value or null if either it is unset or access forbidden.
   */
  String getenv(String name) {
    if (!restrictSystemProps) {
      return System.getenv(name);
    } else {
      return null;
    }
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

1. Simplify the configuration value: nested variable expansion beyond depth 20 indicates a recursive or overly deep property reference.

Example fix

Replace the deeply nested ${...} chain with a direct value.

When it happens

Trigger: Raised at runtime when the documented precondition or configuration requirement for this operation is violated.

Common situations: Misconfigured or missing property, invalid user input, or calling the API before its prerequisites are met.

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/d603ae31da0a42f5. Report an issue: GitHub.