grpc-ecosystem/grpc-gateway · error

%s.%s: %s is a protobuf message type. Protobuf message types

Error message

%s.%s: %s is a protobuf message type. Protobuf message types cannot be used as path parameters, use a scalar value type (such as string) instead

What it means

Validation error from Registry.newParam: the final component of the path-parameter field path is a protobuf message (or group) type that is not a well-known type. Non-WKT messages cannot be serialized into a single URL path segment, so the parameter cannot be built and generation fails; the error names the method, field and suggested scalar alternative.

Source

Thrown at internal/descriptor/services.go:269

	if err != nil {
		return Parameter{}, err
	}
	l := len(fields)
	if l == 0 {
		return Parameter{}, fmt.Errorf("invalid field access list for %s", path)
	}
	target := fields[l-1].Target
	switch target.GetType() {
	case descriptorpb.FieldDescriptorProto_TYPE_MESSAGE, descriptorpb.FieldDescriptorProto_TYPE_GROUP:
		if grpclog.V(2) {
			grpclog.Infoln("found aggregate type:", target, target.TypeName)
		}
		if IsWellKnownType(*target.TypeName) {
			if grpclog.V(2) {
				grpclog.Infoln("found well known aggregate type:", target)
			}
		} else {
			return Parameter{}, fmt.Errorf("%s.%s: %s is a protobuf message type. Protobuf message types cannot be used as path parameters, use a scalar value type (such as string) instead", meth.Service.GetName(), meth.GetName(), path)
		}
	}
	return Parameter{
		FieldPath: FieldPath(fields),
		Method:    meth,
		Target:    fields[l-1].Target,
	}, nil
}

func (r *Registry) newBody(meth *Method, path string) (*Body, error) {
	switch path {
	case "":
		return nil, nil
	case "*":
		return &Body{FieldPath: nil}, nil
	}
	msg := meth.RequestType
	fields, err := r.resolveFieldPath(msg, path, false)

View on GitHub (pinned to a58a4436a3)

Solutions

1. Use a scalar field (string, int, etc.) as the path parameter instead of a nested message.
2. If a well-known type (e.g. google.protobuf.Timestamp) is needed, confirm it is recognized by IsWellKnownType.
3. Restructure the request so the message goes in the body or query parameters.

When it happens

Trigger: Thrown at internal/descriptor/services.go:269 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grpc-ecosystem/grpc-gateway@a58a4436a3 (2026-09-02). Data as JSON: /api/errors/5dfc8872b87f6fac. Report an issue: GitHub.