grpc-ecosystem/grpc-gateway · error

cannot use path parameter in client streaming

Error message

cannot use path parameter in client streaming

What it means

Sentinel-style validation error raised by loadServices when building bindings: an HttpRule path template for a method whose client_streaming flag is true compiled to a template containing path parameters (tmpl.Fields non-empty). gRPC-gateway cannot fill path variables from a request body that the client streams, so the file cannot be bound and code generation aborts.

Source

Thrown at internal/descriptor/services.go:149

			custom := opts.GetCustom()
			httpMethod = custom.Kind
			pathTemplate = custom.Path

		default:
			if grpclog.V(1) {
				grpclog.Infof("No pattern specified in google.api.HttpRule: %s", md.GetName())
			}
			return nil, nil
		}

		parsed, err := httprule.Parse(pathTemplate)
		if err != nil {
			return nil, err
		}
		tmpl := parsed.Compile()

		if md.GetClientStreaming() && len(tmpl.Fields) > 0 {
			return nil, errors.New("cannot use path parameter in client streaming")
		}

		b := &Binding{
			Method:     meth,
			Index:      idx,
			PathTmpl:   tmpl,
			HTTPMethod: httpMethod,
		}

		for _, f := range tmpl.Fields {
			param, err := r.newParam(meth, f)
			if err != nil {
				return nil, err
			}
			b.PathParams = append(b.PathParams, param)
		}

		// TODO(yugui) Handle query params

View on GitHub (pinned to a58a4436a3)

Solutions

1. Remove path parameters (e.g. {id}) from the HttpRule path template for the client-streaming method, using a static path or wildcard-free template.
2. Switch the method to server-streaming or unary if path parameters are required.
3. Move the identifying data into the streamed request message fields instead of the URL path.

When it happens

Trigger: Thrown at internal/descriptor/services.go:149 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/0ecb5a46b16ea07b. Report an issue: GitHub.