apache/beam · error · IllegalArgumentException

Unsupported log level '%s' requested for %s. Must be one of

Error message

Unsupported log level '%s' requested for %s. Must be one of %s.

What it means

SdkHarnessOptions.LogOverrides.from parses a requested log level per module and maps it to the LogLevel enum. This IllegalArgumentException is thrown when the level string is not a valid LogLevel enum constant (only "WARNING" has a special alias to "WARN"), and the message lists the supported values.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/SdkHarnessOptions.java:352

     * {@code Name} generally represents the fully qualified Java {@link Class#getName() class
     * name}, or fully qualified Java {@link Package#getName() package name}, or custom logger name.
     * The {@code LogLevel} represents the log level and must be one of {@link LogLevel}.
     */
    @JsonCreator(mode = JsonCreator.Mode.DELEGATING)
    public static SdkHarnessLogLevelOverrides from(Map<String, String> values) {
      checkArgumentNotNull(values, "Expected values to be not null.");
      SdkHarnessLogLevelOverrides overrides = new SdkHarnessLogLevelOverrides();
      for (Map.Entry<String, String> entry : values.entrySet()) {
        String module = entry.getKey();
        String level = entry.getValue();
        if (level.equals("WARNING")) {
          // alias: "WARNING" -> "WARN"
          level = "WARN";
        }
        try {
          overrides.addOverrideForName(module, LogLevel.valueOf(level));
        } catch (IllegalArgumentException e) {
          throw new IllegalArgumentException(
              String.format(
                  "Unsupported log level '%s' requested for %s. Must be one of %s.",
                  level, module, Arrays.toString(LogLevel.values())));
        }
      }
      return overrides;
    }
  }

  /**
   * Open modules needed for reflection that access JDK internals with Java 9+.
   *
   * <p>With JDK 16+, <a href="#{https://openjdk.java.net/jeps/403}">JDK internals are strongly
   * encapsulated</a> and can result in an InaccessibleObjectException being thrown if a tool or
   * library uses reflection that access JDK internals. If you see these errors in your worker logs,
   * you can pass in modules to open using the format {@code
   * module/package=target-module[,module2/package2=another-target-module]} to allow access to the
   * library. E.g. {@code --jdkAddOpenModules=java.base/java.lang=jamm}. This will set {@code

View on GitHub (pinned to 12126d8942)

Solutions

1. Use one of the exact LogLevel values (see the message's list, e.g. DEBUG, INFO, WARN, ERROR)
2. Change "WARNING"-style spellings: "WARNING" is aliased to "WARN" but "ERROR" vs "ERR" etc. must match the enum exactly
3. Normalize/uppercase the level string and validate against LogLevel.values() before calling from()

Example fix

// before
LogOverrides.from(ImmutableMap.of("org.apache.beam", "ERROR")); // if ERROR not in enum
// after
LogOverrides.from(ImmutableMap.of("org.apache.beam", "WARN")); // exact LogLevel value

String lvl = requested.trim().toUpperCase();
if (!lvl.equals("WARNING")) {
  try { LogLevel.valueOf(lvl); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Bad log level " + requested + "; use " + Arrays.toString(LogLevel.values())); }
}

boolean isValidLogLevel(String s) { return "WARNING".equalsIgnoreCase(s) || Arrays.stream(LogLevel.values()).anyMatch(l -> l.name().equalsIgnoreCase(s)); }

try { overrides.addOverrideForName(module, LogLevel.valueOf(level)); } catch (IllegalArgumentException e) { /* fall back to INFO and log a warning */ }

When it happens

Trigger: Calling SdkHarnessOptions.LogOverrides.from(...) with a map containing a level like "error", "severe", "ERROR", "FATAL", or any spelling not exactly matching a LogLevel value.

Common situations: Config files using SLF4J or JUL-style level names (e.g. "ERROR") that don't match Beam's enum, casing differences, or renamed levels across Beam versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown log level ${level}. Valid log levels are ${validLeve
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed
• Runner does not support draining.
• cannot encode a null Integer

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/0efc9864afcfd524. Report an issue: GitHub.