EC
UNKNOWN
gRPCERRORCriticalServer-SideMEDIUM confidence

An unknown error occurred

What this means

Indicates an error that cannot be mapped to any other status code. This often signifies an unexpected server-side exception or a bug in the gRPC framework itself.

Why it happens
  1. 1An unhandled exception was thrown in the server-side method implementation.
  2. 2The status code returned from a downstream service could not be mapped to a gRPC status.
  3. 3A bug within the gRPC library or a proxy server.
  4. 4The server returned a status that is not part of the standard gRPC status codes.
How to reproduce

The server-side implementation of an RPC method throws an unexpected exception.

trigger — this will error
trigger — this will error
// Server-side implementation (e.g., in Node.js)
async myMethod(call, callback) {
  throw new Error("Something completely unexpected happened!");
}

expected output

StatusCode.UNKNOWN: An unknown error occurred

Fix 1

Add Server-Side Error Handling

WHEN When the server code throws uncaught exceptions.

Add Server-Side Error Handling
// Server-side implementation with proper error handling
async myMethod(call, callback) {
  try {
    // ... business logic ...
  } catch (err) {
    // Log the error and return a more specific status code
    console.error(err);
    callback({ code: grpc.status.INTERNAL, details: "Internal server error" });
  }
}

Why this works

Catching exceptions allows you to map them to more descriptive gRPC status codes, providing better context to the client.

Fix 2

Inspect Server Logs

WHEN When an UNKNOWN error is received by the client.

Inspect Server Logs
// Check server logs for stack traces or error messages near the time of the call.
// Look for uncaught exceptions or panics.
journalctl -u my-grpc-service.service

Why this works

Server logs are the primary source for diagnosing the root cause of an UNKNOWN error.

What not to do

✕ Expose raw exception details to the client

Leaking implementation details or stack traces can be a security risk and is not helpful for the client.

Sources

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All gRPC errors