apache/hadoop · error · HadoopIllegalArgumentException

conf is not set

Error message

conf is not set

What it means

RPC.Server.Builder.build() validates its mandatory fields and throws HadoopIllegalArgumentException("conf is not set") when setConf was never called. The Configuration supplies bind behavior, secrets, and the protocol engine lookup (getProtocolEngine), so a Server cannot be constructed without it.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/RPC.java:980

    }
    
    /**
     * @return Default: null.
     * @param alignmentContext input alignmentContext.
     */
    public Builder setAlignmentContext(AlignmentContext alignmentContext) {
      this.alignmentContext = alignmentContext;
      return this;
    }

    /**
     * @return Build the RPC Server.
     * @throws IOException on error
     * @throws HadoopIllegalArgumentException when mandatory fields are not set
     */
    public Server build() throws IOException, HadoopIllegalArgumentException {
      if (this.conf == null) {
        throw new HadoopIllegalArgumentException("conf is not set");
      }
      if (this.protocol == null) {
        throw new HadoopIllegalArgumentException("protocol is not set");
      }
      if (this.instance == null) {
        throw new HadoopIllegalArgumentException("instance is not set");
      }
      
      return getProtocolEngine(this.protocol, this.conf).getServer(
          this.protocol, this.instance, this.bindAddress, this.port,
          this.numHandlers, this.numReaders, this.queueSizePerHandler,
          this.verbose, this.conf, this.secretManager, this.portRangeConfig,
          this.alignmentContext);
    }
  }
  
  /** An RPC Server. */
  public abstract static class Server extends org.apache.hadoop.ipc.Server {

View on GitHub (pinned to 2add963021)

Solutions

1. Call builder.setConf(conf) with a non-null Configuration before build().
2. Verify the Configuration was actually constructed (new Configuration() or loaded from resources) and not left null.
3. Make setConf the first setter in the chain so later edits cannot silently drop it.

Example fix

// before
Server s = new RPC.Server.Builder()
    .setProtocol(MyProto.class)
    .setInstance(impl)
    .build(); // throws: conf is not set
// after
Server s = new RPC.Server.Builder()
    .setConf(conf)
    .setProtocol(MyProto.class)
    .setInstance(impl)
    .build();

if (conf == null) {
  throw new IllegalStateException("Configuration required before building RPC server");
}
new RPC.Server.Builder().setConf(conf)...build();

When it happens

Trigger: Building an RPC server via new RPC.Server.Builder() without a .setConf(conf) call; passing a Configuration variable that was never initialized and is null.

Common situations: Hand-rolled test RPC servers; copy-pasted builder chains where the setConf line was dropped; refactors that moved Configuration creation after the build() call.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• protocol is not set
• instance is not set
• Could not find a free port in ${range}
• Unknown method {} called on {} protocol.
• Unknown protocol: {}

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