Apache APISIX gRPC Transcoding Returns 400

You encounter a apisix configuration issue that prevents your workflow from completing. This guide walks through the fix step by step.

Wrong ❌

{
  "plugins": {
    "grpc-transcode": {
      "proto_id": "my-service-proto",
      "method": "ListUsers"
      # Missing service and parameter mapping
    }
  }
}

Wrong Output

All transcoded REST requests return 400. Protobuf mapping not found. service must be specified.

Right ✅

# Upload proto file via Admin API
PUT /apisix/admin/protos/1
{
  "content": "syntax = 'proto3'; package my.service; service MyService { rpc ListUsers (ListUsersRequest) returns (UserList); } message ListUsersRequest { string page_size = 1; } ..."
}
# Route with grpc-transcode plugin
PUT /apisix/admin/routes/1
{
  "uri": "/my.service.MyService/ListUsers",
  "plugins": {
    "grpc-transcode": {
      "proto_id": "1",
      "service": "my.service.MyService",
      "method": "ListUsers",
      "pb_option": ["auto_bind", "enable_hooks"]
    }
  },
  "upstream": { "type": "roundrobin", "nodes": { "grpc-backend:50051": 1 } }
}

Right Output

gRPC transcoding working: REST POST /my.service.MyService/ListUsers -> gRPC call to backend -> JSON response.

Prevention

• Upload proto definitions before creating transcoded routes.
• Specify the full service name including the package.
• Match the method name exactly as defined in the proto.
• Use pb_option auto_bind for automatic parameter binding.
• Test the transcoded REST endpoint with HTTP/1.1.

DodaTech applies similar defensive patterns across Doda Browser, DodaZIP, and Durga Antivirus Pro infrastructure for production reliability.

Common Mistakes with grpc transcode

1. Misunderstanding that String is [Char] with poor performance for large text operations
2. Using foldl instead of foldl' causing stack overflow on large lists
3. Forgetting deriving (Show, Eq) on custom data types needed for debugging

These mistakes appear frequently in real-world APISIX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

This quick fix is part of the DodaTech infrastructure engineering series. Learn more at DodaTech tutorials.