Troubleshooting gRPC with Cloud Endpoints

This page provides specific troubleshooting information for services using gRPC with Cloud Endpoints. You should also refer to Troubleshooting the Extensible Service Proxy for general troubleshooting information.

Service configuration and deployment

Problem: The protoc command to generate your descriptor file fails.

    protoc \
        --include_imports \
        --include_source_info \
        --descriptor_set_out=api_descriptor.pb \

Troubleshooting tips:

  • Make sure your protoc version is up-to-date.
  • You may need to provide additional flags (--proto_path or its short form -I) for the root directories for imported .proto files. You can find out more in the protocol buffers documentation.
  • Make sure --include_imports is specified.

Problem: Deploying your service configuration to Endpoints fails.

    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

Troubleshooting tips:

Check your .proto for mis-matched fields between your protocol buffer messages and transcoding mappings. This produces the following error when your deployment fails:

    ERROR: ( INVALID_ARGUMENT: Cannot convert to service config.
    http: undefined field '<unknown>' on message '<RequestType>'

For example, the following .proto would produce this error. The mapping option on Unary specifies a field named undefined that isn't in the Request message definition.

    rpc Unary(Request) Response {
      option (google.api.http) { get : "/{undefined}" };

    message Request {
      string defined = 1;

Backend unreachable

Problem: Your client can't reach the service backend. For HTTP clients, the error looks like this:

     "code": 14,
     "message": "upstream backend unavailable",

For gRPC clients, it looks like this:

    rpc error: code = 14 desc = upstream backend unavailable:

Troubleshooting tips:

Tips are the same as for an OpenAPI service receiving a cURL BAD_GATEWAY response.

Extensible Service Proxy unreachable

Problem: Client receives gRPC response:

    rpc error: code = 13 desc = transport is closing:

Troubleshooting tips:

Check the ESP error logs. You can find out more about how to do this for your deployment in the following guides:

Authentication and API keys

Problem: Requests pass without oauth check

Troubleshooting tip:

Make sure there is an authentication section that has your OAuth definition in your gRPC API configuration file. An example configuration file is available in the Cloud Endpoints GitHub repository. Although this example is for OpenAPI, the syntax is the same for gRPC.

Problem: Method doesn't allow unregistered callers

Troubleshooting tip:

If you didn't set allow_unregistered_calls: true in your gRPC api config, and make calls without appending api-key, you can use a Browser or Server API key from the Cloud Console Credentials page.

Unexpected responses

Problem: My HTTP response looks like it's binary.

Troubleshooting tip:

If the HTTP response looks like it is binary, there is a chance you are intending to use the HTTP1.1 port but hitting the API via the HTTP2 port. Check your port configuration options for ESP, the -p and -P short form flags look very similar. Use the long form flags instead: --http_port for HTTP1.1 and --http2_port for HTTP2.

A misconfiguration of the ESP backend may also cause unexpected responses. Make sure the backend flag (-a or --backend) is set to a gRPC URL such as --backend=grpc:// if you are using gRPC.

For more details on the Endpoints Proxy flags, please see the Proxy Startup Options

Send feedback about...

Cloud Endpoints with gRPC