An unexpected exception reaches a gRPC caller with its message; the HTTP side masks the same error

[AlexeyShalaev]

Measured on 0.10.0 with one service running a FastApiEntrypoint and a GrpcEntrypoint over the same use case, map_service_errors left at its default. Every row is the same call made twice, once per transport:

    case         HTTP                                                          gRPC
    missing      404 code=order_not_found  detail="no order with id 42"        NOT_FOUND: no order with id 42  [x-error-code=order_not_found]
    paid         409 code=order_already_paid                                   ALREADY_EXISTS: order 42 was paid at 09:12  [x-error-code=order_already_paid]
    forbidden    403 code=not_your_order                                       PERMISSION_DENIED: ...  [x-error-code=not_your_order]
    provider     503 code=payment_provider_down                                UNAVAILABLE: ...  [x-error-code=payment_provider_down]
    ledger       500 code=internal_error, no detail                            INTERNAL: internal_error  [x-error-code=internal_error]
    unexpected   500 code=internal_error, no detail                            UNKNOWN: Unexpected <class 'RuntimeError'>: dividing by the number of retries, which is zero
    ok           200                                                           OK

Five of the seven rows are exactly what the design promises. The unexpected row is not, and it is the row where an exception nobody planned for reaches the caller.

The case is a plain RuntimeError from the use case — not a ServiceError. Over HTTP, the default exception handlers turn it into a 500 with code=internal_error and no detail, and the message goes to the log where it belongs. Over gRPC it reaches the caller in full: the status is UNKNOWN rather than INTERNAL, and the details carry repr of the exception. In this lab the message is harmless; in the service this lab is modelled on, the same path had a DSN with a password in the exception text, and it would have gone over the wire to whoever made the call.

The cause is the scope of the mapping: ServiceErrorInterceptor maps ServiceError and leaves everything else to grpc.aio, whose default for an unhandled exception is UNKNOWN with "Unexpected {type}: {message}" in the details. The HTTP side does not have that gap because its default handlers have an Exception catch-all.

What I think it needs: the gRPC error mapping should treat a non-ServiceError exception the way the HTTP side does — abort with INTERNAL, a generic detail, the same internal_error code in the trailing metadata, and the real exception logged with its traceback at ERROR. CancelledError and AbortError keep their current behaviour, since one is the caller leaving and the other is a deliberate status a handler already chose. The two transports agreeing on this is the whole promise of the shared error model, and today the promise holds for errors you declared and breaks for the ones you did not.

Worth checking in the same pass:

• ALREADY_EXISTS for ErrorKind.CONFLICT reads oddly for a state conflict that is not a duplicate key (FAILED_PRECONDITION and ABORTED are the usual gRPC spellings), and GRPC_STATUS_BY_KIND is the table where that decision lives. I would not change it without a reason, but the mapping table deserves a line in the docs saying why each kind maps where it does.
• The docs say public=False masks "at the transport". That is true for both transports today. It is worth a test that asserts it for both, next to the new one, because that is the property this issue's row broke for unexpected exceptions.

Lab: service.py and driver.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-07-transport-independent-errors.

[AlexeyShalaev]

Reproduced on 0.10.0 with your lab, unchanged — same seven rows, same one that is wrong:

    unexpected   500 code=internal_error, no detail   UNKNOWN: Unexpected <class 'RuntimeError'>: dividing by the number of retries, which is zero

and the server log shows the traceback coming out of grpc._cython.cygrpc, not out of us. Your
diagnosis is right: ServiceErrorInterceptor only claims ServiceError, everything else falls
through to grpc.aio, and grpc.aio answers UNKNOWN with repr of the exception. Over HTTP the
same exception hits a catch-all and is masked. So the promise holds for the errors you declared and
breaks for the ones you did not — which is the wrong way round, because the undeclared ones are
exactly the ones whose text nobody has vetted.

What I am going to do

Port the layer the HTTP side already has. FastApiEntrypoint does not do this in an exception
handler alone — it installs UnhandledErrorMiddleware as a distinct layer of the stack, inside
the context layer so the masked 500 and its log line still carry the request id, and outside the
rest so nothing below it can leave without a status. The gRPC adapter gets the same thing:

UnitScopeInterceptor            ← outermost: correlation ids are bound here
  UnhandledErrorInterceptor     ← new: inside the context layer, so the log carries the request id
    metrics interceptor
      your static interceptors
      your interceptors_factory results
        ServiceErrorInterceptor ← innermost, unchanged
          your servicer

UnhandledErrorInterceptor re-raises grpc.aio.AbortError and grpc.RpcError (a status somebody
chose deliberately) and never sees asyncio.CancelledError, which is a BaseException. Anything
else is logged with logger.exception and aborted with INTERNAL, detail internal_error, and
x-error-code: internal_error in the trailing metadata — byte for byte what a public=False
ServiceError already produces over gRPC today. After the change your ledger and unexpected
rows become identical, which is the property worth having: a caller cannot tell an error you hid
from an error you never knew about, and neither one carries a message you did not write.

No new keyword argument. On the HTTP side this layer has no toggle either — it is installed
unconditionally, because "do not leak" is not a preference. map_service_errors=False keeps
turning off ServiceError mapping only.

What I rejected

Folding the catch-all into ServiceErrorInterceptor. Shortest diff, wrong position.
ServiceErrorInterceptor is innermost by design, so it would swallow every exception before your
own interceptors could map theirs. Starlette dispatches handlers by type, so on HTTP your handler
for your exception type always wins over the Exception catch-all; a separate outer layer is what
reproduces that ordering here. As a bonus it also covers an exception raised by an interceptor
rather than by the servicer.

Installing grpc-server-kit's AsyncExceptionHandlerInterceptor by default. It exists and it
maps unknown exceptions to INTERNAL, but it also maps ValueError to INVALID_ARGUMENT,
TimeoutError to DEADLINE_EXCEEDED, FileNotFoundError to NOT_FOUND — and over HTTP those
same three exceptions are a masked 500. Adopting it would fix the leak and re-open the disagreement
somewhere else. It also sends no x-error-code. It stays what it is: something you compose when
you want that mapping, and because it would sit inside the new layer, composing it still works
exactly as before.

CONFLICT → ALREADY_EXISTS

Keeping it, and writing down why, because you are right that the table has no stated rationale.

ABORTED is the tempting alternative, and it is the one that would do damage: the gRPC spec tells
clients to retry ABORTED at a higher level (it is the transaction-conflict code), and "this order
was already paid" is the least retryable thing in the domain. FAILED_PRECONDITION is already
taken by PRECONDITION_FAILED, and the table is worth keeping injective so a status maps back to
one kind. ALREADY_EXISTS is then the only code that carries 409 without also carrying advice.
Add that a client wanting to tell a duplicate key from a state conflict has x-error-code for it,
and the wire change buys nothing it does not already have. The docs get the reasoning next to the
table.

Tests and docs

• gRPC: an unexpected exception aborts INTERNAL / internal_error with the code in trailing
  metadata and the exception text nowhere on the wire; a deliberate AbortError and a
  CancelledError pass through; the traceback reaches the log; the interceptor lands in the right
  position in the chain. Plus a real-server test that makes the reporter's call over a socket.
• Both transports: one module asserting the parity directly — the same public=False error and the
  same unexpected exception, over HTTP and over gRPC, produce the same conclusion for a caller.
  That is the property this row broke, and it should fail loudly next time.
• Docs: the errors concept page (the kinds table, why each kind lands where it does, and the
  unhandled row), the gRPC adapter page (error mapping and the ordering diagram), and agents.md.

[AlexeyShalaev]

Shipped in #52, CI green. Your lab, unmodified, against the branch:

    case         HTTP                                                          gRPC
    missing      404 code=order_not_found  detail="no order with id 42"        NOT_FOUND: no order with id 42  [x-error-code=order_not_found]
    paid         409 code=order_already_paid                                   ALREADY_EXISTS: order 42 was paid at 09:12  [x-error-code=order_already_paid]
    forbidden    403 code=not_your_order                                       PERMISSION_DENIED: ...  [x-error-code=not_your_order]
    provider     503 code=payment_provider_down                                UNAVAILABLE: ...  [x-error-code=payment_provider_down]
    ledger       500 code=internal_error, no detail                            INTERNAL: internal_error  [x-error-code=internal_error]
    unexpected   500 code=internal_error, no detail                            INTERNAL: internal_error  [x-error-code=internal_error]
    ok           200                                                           OK

The unexpected row is now the ledger row, character for character, which is the answer to what
you were actually asking: a caller cannot tell an error you hid from an error you never knew about.
The RuntimeError and its traceback now come out of servicewright.adapters.grpc.errors at ERROR
with the RPC's correlation ids on the record, instead of out of grpc._cython.cygrpc uncorrelated.

UnhandledErrorInterceptor does it — a distinct layer rather than a wider ServiceErrorInterceptor,
because the mapper is innermost by design and folding the catch-all into it would have taken every
exception before your own interceptors could map theirs. It sits where the HTTP counterpart sits:
inside the layer that binds the correlation ids, outside everything else. Your own interceptors,
including grpc-server-kit's AsyncExceptionHandlerInterceptor if that mapping is what you want, are
inside it and still get first refusal; nothing about composing them changes.

Nothing to change on your side. Two consequences worth knowing:

• It is installed unconditionally, like UnhandledErrorMiddleware over HTTP. map_service_errors=False
  still turns off only the mapping of declared errors — with it off, a ServiceError now arrives as a
  masked INTERNAL rather than as UNKNOWN plus its message.
• A client branching on UNKNOWN to spot a server crash should branch on INTERNAL now. That is the
  correction, not a side effect.

CONFLICT keeps ALREADY_EXISTS. I went looking for a reason to move it and found the reason not to:
ABORTED is also 409, but it is the transaction-conflict code and the contract tells clients to retry
it at a higher level — the worst possible advice for "this order was already paid". FAILED_PRECONDITION
is spoken for by PRECONDITION_FAILED, and keeping the table injective is what lets a gateway translate
in both directions. And a client that needs to tell a duplicate key from a state conflict has
x-error-code, which carries the exact code either way. So: no wire change, and the reasoning now lives
next to the table on the errors page and in the source, which was the real gap you spotted.

Your second suggestion is tests/unit/test_error_parity.py — one property, parametrized over both
transports and over both kinds of hidden failure, so the next time one side drifts it fails on that side
and names it. On master five of its six cases pass and exactly one fails: the undeclared exception over
gRPC, this issue's row.