apache/hadoop · error · HadoopIllegalArgumentException

protocol is not set

Error message

protocol is not set

What it means

RPC.Server.Builder.build() requires the protocol interface (the RPC contract class) and throws HadoopIllegalArgumentException("protocol is not set") when .setProtocol was never called. The protocol class determines which RPC engine and method dispatcher the server uses.

Source

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

     * @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 {

    boolean verbose;

View on GitHub (pinned to 2add963021)

Solutions

1. Call .setProtocol(YourProtocol.class) before build().
2. When resolving the protocol class by name, fail with a clear error when the class cannot be loaded instead of passing null.
3. Keep the builder chain for a server in one place so all mandatory setters stay together.

Example fix

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

Class<?> proto = resolveProtocolClass(); // e.g. Class.forName with error handling
if (proto == null) {
  throw new IllegalStateException("protocol class could not be resolved");
}
new RPC.Server.Builder().setConf(conf).setProtocol(proto)...build();

When it happens

Trigger: Calling build() without .setProtocol(...); passing a protocol class resolved by name (e.g., Class.forName) where the lookup failed and produced null.

Common situations: Config-driven server construction where the protocol class name is mistyped or the class is not on the classpath; trimmed builder chains in tests and examples.

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

• Unknown protocol: {}
• conf is not set
• instance is not set
• Serverside implements {}. The following requested protocol i
• Serverside implements {}. The following requested protocol i

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