What causes "invalid method name: should start with /" in grpc/grpc-go?

Ensure method names passed to ParseMethod always start with '/' (e.g., '/package.Service/Method').

invalid method name: should start with /

Error message

invalid method name: should start with /

What it means

Returned by grpcutil.ParseMethod when the method name does not start with '/'. gRPC method names follow the format '/package.Service/Method'—the leading slash is mandatory. ParseMethod strips it then splits on the last '/' to extract service and method names. This is an internal utility used by binary logging, observability, and stats handling to decompose the full method path.

Source

Thrown at internal/grpcutil/method.go:30

 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

package grpcutil

import (
	"errors"
	"strings"
)

// ParseMethod splits service and method from the input. It expects format
// "/service/method".
func ParseMethod(methodName string) (service, method string, _ error) {
	if !strings.HasPrefix(methodName, "/") {
		return "", "", errors.New("invalid method name: should start with /")
	}
	methodName = methodName[1:]

	pos := strings.LastIndex(methodName, "/")
	if pos < 0 {
		return "", "", errors.New("invalid method name: suffix /method is missing")
	}
	return methodName[:pos], methodName[pos+1:], nil
}

// baseContentType is the base content-type for gRPC.  This is a valid
// content-type on its own, but can also include a content-subtype such as
// "proto" as a suffix after "+" or ";".  See
// https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requests
// for more details.
const baseContentType = "application/grpc"

// ContentSubtype returns the content-subtype for the given content-type.  The

View on GitHub (pinned to 0c51461d27)

Solutions

Ensure method names passed to ParseMethod always start with '/' (e.g., '/package.Service/Method').
If intercepting at the HTTP layer, verify proxies preserve the leading '/' in the :path pseudo-header.
Add a prefix '/' before calling ParseMethod if your string lacks it.
Log the raw method string to identify where the malformed name originates.

Example fix

// before
svc, method, err := grpcutil.ParseMethod("myapp.UserService/GetUser")
// after
svc, method, err := grpcutil.ParseMethod("/myapp.UserService/GetUser")

Defensive patterns

Strategy: validation

Validate before calling

// Validate method name format before calling ParseMethod.
func isValidMethodName(method string) bool {
    return strings.HasPrefix(method, "/") && strings.Count(method, "/") >= 2
}
if !isValidMethodName(method) {
    return errors.New("method must be '/package.Service/Method'")
}
svc, m, err := grpcutil.ParseMethod(method)

Try / catch

svc, method, err := grpcutil.ParseMethod(name)
if err != nil {
    if strings.Contains(err.Error(), "should start with /") {
        name = "/" + name
        svc, method, err = grpcutil.ParseMethod(name)
    }
}

Prevention

Always construct gRPC method names with the leading '/' using the standard format.
Validate method strings from external sources before parsing.
Use grpc.MethodFromServerStream to get well-formed method names rather than constructing manually.
Log raw method names in interceptors to catch malformed values early.

When it happens

Trigger: Calling ParseMethod with a string like 'package.Service/Method' (missing leading '/') or an empty/arbitrary string. Can happen if code constructs method names manually without the gRPC convention, or if a proxy/gateway rewrites the :path header and drops the leading slash.

Common situations: Custom interceptors or stats handlers that parse ctx.Value(methodKey) or full method paths; gRPC-Web or HTTP gateway proxies that mangle the request path; observability/binary-logging config pointing at malformed method names; programmatic construction of method strings.

Related errors

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/a8c880aa81b8e725. Report an issue: GitHub.