apache/hadoop · error · IllegalArgumentException

Could not set handler for signal "${name}".This can happen i

Error message

Could not set handler for signal "${name}".This can happen if the JVM has the -Xrs set.

What it means

The ServiceLauncher registers graceful-shutdown handlers for SIGINT (IrqHandler.CONTROL_C="INT") and SIGTERM via InterruptEscalator.register() -> IrqHandler.bind(), which installs a sun.misc.Signal handler. If the JVM refuses the registration, bind throws IllegalArgumentException "Could not set handler for signal \"<name>\". This can happen if the JVM has the -Xrs set." - -Xrs disables the signal machinery, and some signal names simply do not exist on a given OS.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/service/launcher/IrqHandler.java:93

   */
  public IrqHandler(String name, Interrupted handler) {
    Preconditions.checkArgument(name != null, "Null \"name\"");
    Preconditions.checkArgument(handler != null, "Null \"handler\"");
    this.handler = handler;
    this.name = name;
  }

  /**
   * Bind to the interrupt handler.
   * @throws IllegalArgumentException if the exception could not be set
   */
  public void bind() {
    Preconditions.checkState(signal == null, "Handler already bound");
    try {
      signal = new SignalUtil.Signal(name);
      SignalUtil.handle(signal, this);
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(
          "Could not set handler for signal \"" + name + "\"."
          + "This can happen if the JVM has the -Xrs set.",
          e);
    }
  }

  /**
   * @return the signal name.
   */
  public String getName() {
    return name;
  }

  /**
   * Raise the signal.
   */
  public void raise() {
    SignalUtil.raise(signal);

View on GitHub (pinned to 2add963021)

Solutions

1. Remove -Xrs from the JVM options of processes launched via ServiceLauncher so INT/TERM handlers can bind.
2. If signals are truly unavailable, rely on the separately registered ServiceShutdownHook for orderly shutdown and skip/soft-fail interrupt registration.
3. On cross-platform code, only register signal names valid for the current OS (INT/TERM are safe; HUP is not on Windows).

Example fix

# before: launch fails binding INT/TERM
export HADOOP_OPTS="-Xrs"
hadoop org.example.MyService
# after: drop -Xrs so ServiceLauncher can bind signal handlers
export HADOOP_OPTS=""
hadoop org.example.MyService

// or in code: degrade gracefully when signals are unavailable
try { interruptEscalator.register(IrqHandler.SIGTERM); }
catch (IllegalArgumentException e) { LOG.warn("signal handling disabled: {}", e.getMessage()); }

// Detect -Xrs before registering signal handlers
import java.lang.management.ManagementFactory;
boolean xrs = ManagementFactory.getRuntimeMXBean().getInputArguments()
    .stream().anyMatch(a -> a.equals("-Xrs"));
if (xrs) {
  LOG.warn("-Xrs present: skipping IrqHandler bind; rely on shutdown hooks");
} else {
  interruptEscalator.register(IrqHandler.CONTROL_C);
  interruptEscalator.register(IrqHandler.SIGTERM);
}

try {
  handler.bind();
} catch (IllegalArgumentException e) {
  // signals unavailable (-Xrs / platform): degrade to ServiceShutdownHook-based shutdown
  LOG.warn("Signal handling disabled: {}", e.getMessage());
}

When it happens

Trigger: Launching any ServiceLauncher-based main class with -Xrs in the JVM options (HADOOP_OPTS, JAVA_OPTS, container wrappers like dumb-init-based images); binding a signal name the platform lacks (e.g. "HUP" on Windows); the signal already claimed by another native handler.

Common situations: Container/base-image hardening scripts that copy -Xrs from other JVM deployments; orchestration layers that add -Xrs to suppress signal threads; JVM signal conflicts with native profilers or agents.

Related errors

• Call interrupted
• Can't create keystore
• EXIT_SERVICE_CREATION_FAILURE(56)
• EXIT_COMMAND_ARGUMENT_ERROR(40)
• 40

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