grpc/grpc-java · error · IllegalStateException

No entry in descriptor matching bound method ${fullMethodNam

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.

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)

Solutions

1. Ensure the ServiceDescriptor passed to the builder declares every method you add with addMethod()
2. Rebuild the ServiceDescriptor from the complete set of bound MethodDescriptors
3. Verify full method names (service name + method name) match exactly between bound methods and descriptor entries
4. 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();

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

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

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

• Bound method for ${fullMethodName} not same instance as meth
• No ALTS context information found
• Can't set TLS settings for ALTS
• Counter has overflowed.
• Invalid frame length ${dataLength}

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