12 UNIMPLEMENTED 🔌 API

gRPC Error: 12 UNIMPLEMENTED: unknown service x / Method not found

The server doesn’t have the service or method the client called — proto mismatch, wrong package name, or calling the wrong server.

Seen on: REST API

Meaning

Fully qualified names (package.Service/Method) must match exactly. Outdated generated code, missing service registration on the server, or routing through a proxy to the wrong backend cause it.

Common causes

  • Client and server proto definitions differ
  • Service not registered on the server
  • Wrong package/service name
  • Proxy routing to another service

⚡ Quick fix

  1. List services with grpcurl (reflection)
  2. Regenerate client stubs from the same proto
  3. Register the service in the server setup

Detailed fix by platform

Shell

  1. bash
    grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe orders.v1.OrderService

How to diagnose

  1. Services — Exposed list
  2. Protos — Same version?
  3. Routing — Correct backend?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.