apache/hadoop · error · HadoopIllegalArgumentException

instance is not set

Error message

instance is not set

What it means

RPC.Server.Builder.build() requires the protocol implementation instance (the object that will receive calls) and throws HadoopIllegalArgumentException("instance is not set") when .setInstance was never called. A protocol interface without a serving instance cannot be exported.

Source

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

    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;

    private static final Pattern COMPLEX_SERVER_NAME_PATTERN =
        Pattern.compile("(?:[^\\$]*\\$)*([A-Za-z][^\\$]+)(?:\\$\\d+)?");

View on GitHub (pinned to 2add963021)

Solutions

1. Call .setInstance(implementation) with the non-null object implementing the protocol before build().
2. Check the instance reference right after construction and fail with a descriptive error if it is null.
3. Construct the implementation before the builder chain starts so the reference is provably non-null.

Example fix

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

MyProtocol impl = constructImplementation();
Objects.requireNonNull(impl, "protocol implementation required");
new RPC.Server.Builder().setConf(conf).setProtocol(MyProtocol.class)
    .setInstance(impl).build();

When it happens

Trigger: Calling build() without .setInstance(impl); wiring code that intended to pass the implementation but passed null because construction of the implementation failed earlier.

Common situations: Builders assembled by DI frameworks where the instance bean was missing; test servers configured with only conf and protocol; refactors that moved instance creation after build().

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

• conf is not set
• protocol is not set
• Unknown method {} called on {} protocol.
• Unknown protocol: {}
• Unknown method ${methodName} called on ${connectionProtocolN

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