grpc/grpc-java · error · IllegalStateException

No entry in descriptor matching bound method

Error message

No entry in descriptor matching bound method ${fullMethodName}

What it means

ServerServiceDefinition.Builder.build() checks that every method bound with addMethod() has a matching entry in the ServiceDescriptor. If bound methods remain that have no corresponding descriptor entry, this IllegalStateException is thrown, reporting the first unmatched bound method's full name.

Solutions

Ensure the ServiceDescriptor passed to the builder declares every method you add with addMethod()
Rebuild the ServiceDescriptor from the complete set of bound MethodDescriptors
Verify full method names (service name + method name) match exactly between bound methods and descriptor entries
If generating code, regenerate so descriptor and bound methods stay in sync

Example fix

// before
ServiceDescriptor desc = ServiceDescriptor.newBuilder("svc").build(); // missing method
builder = ServerServiceDefinition.builder(desc).addMethod(barMethod);
// after
ServiceDescriptor desc = ServiceDescriptor.newBuilder("svc")
    .addMethod(barMethod)
    .build();
ServerServiceDefinition def = ServerServiceDefinition.builder(desc).addMethod(barMethod).build();

Defensive patterns

Strategy: validation

Validate before calling

Set<String> descNames = descriptor.getMethods().stream().map(MethodDescriptor::getFullMethodName).collect(toSet());
assert boundMethods.stream().map(MethodDescriptor::getFullMethodName).allMatch(descNames::contains);

Try / catch

try {
  def = builder.build();
} catch (IllegalStateException e) {
  throw new ConfigurationException("Bound method missing from descriptor: " + e.getMessage(), e);
}

Prevention

Build the ServiceDescriptor from the full list of bound methods, never a hand-maintained list
Keep method registration in one place to avoid drift between builder and descriptor
Write a test that builds every service definition at startup

When it happens

Trigger: Calling build() after addMethod() with a MethodDescriptor whose full method name does not appear in the builder's ServiceDescriptor — e.g. adding a method the service descriptor doesn't declare, or a ServiceDescriptor built before all methods were added.

Common situations: Manually wiring a server service definition where the ServiceDescriptor was created from a stale/partial method list; adding streaming methods to the builder but forgetting to include them in the descriptor; mismatched service names between the method and descriptor.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/571a6368d8727aa8. Report an issue: GitHub.

Appendix: source

Thrown at api/src/main/java/io/grpc/ServerServiceDefinition.java:147

        }
        serviceDescriptor = new ServiceDescriptor(serviceName, methodDescriptors);
      }
      Map<String, ServerMethodDefinition<?, ?>> tmpMethods = new HashMap<>(methods);
      for (MethodDescriptor<?, ?> descriptorMethod : serviceDescriptor.getMethods()) {
        ServerMethodDefinition<?, ?> removed = tmpMethods.remove(
            descriptorMethod.getFullMethodName());
        if (removed == null) {
          throw new IllegalStateException(
              "No method bound for descriptor entry " + descriptorMethod.getFullMethodName());
        }
        if (removed.getMethodDescriptor() != descriptorMethod) {
          throw new IllegalStateException(
              "Bound method for " + descriptorMethod.getFullMethodName()
                  + " not same instance as method in service descriptor");
        }
      }
      if (tmpMethods.size() > 0) {
        throw new IllegalStateException(
            "No entry in descriptor matching bound method "
                + tmpMethods.values().iterator().next().getMethodDescriptor().getFullMethodName());
      }
      return new ServerServiceDefinition(serviceDescriptor, methods);
    }
  }
}

View on GitHub (pinned to 64daddc1f3)