What causes "Encountered error during serialized access" in grpc/grpc-java?

Inspect the cause of the RuntimeException (getCause()): InterruptedException or ExecutionException reveals the underlying delegate failure.

grpc/grpc-java · error · RuntimeException

Encountered error during serialized access

Error message

Encountered error during serialized access

What it means

SerializingServerCall (installed by TransmitStatusRuntimeExceptionInterceptor) moves every ServerCall method onto a single serializing executor and blocks the caller on a SettableFuture. If the delegated isReady() computation fails or the wait is interrupted, the original exception is wrapped in a RuntimeException with the fixed message 'Encountered error during serialized access'. It signals that an exception escaped the serialized execution of the call, not a gRPC protocol problem per se.

Source

Thrown at util/src/main/java/io/grpc/util/TransmitStatusRuntimeExceptionInterceptor.java:188

            SerializingServerCall.super.close(status, trailers);
          }
        }
      });
    }

    @Override
    public boolean isReady() {
      final SettableFuture<Boolean> retVal = SettableFuture.create();
      serializingExecutor.execute(new Runnable() {
        @Override
        public void run() {
          retVal.set(SerializingServerCall.super.isReady());
        }
      });
      try {
        return retVal.get();
      } catch (InterruptedException e) {
        throw new RuntimeException(ERROR_MSG, e);
      } catch (ExecutionException e) {
        throw new RuntimeException(ERROR_MSG, e);
      }
    }

    @Override
    public boolean isCancelled() {
      final SettableFuture<Boolean> retVal = SettableFuture.create();
      serializingExecutor.execute(new Runnable() {
        @Override
        public void run() {
          retVal.set(SerializingServerCall.super.isCancelled());
        }
      });
      try {
        return retVal.get();
      } catch (InterruptedException e) {
        throw new RuntimeException(ERROR_MSG, e);

View on GitHub (pinned to 64daddc1f3)

Solutions

Inspect the cause of the RuntimeException (getCause()): InterruptedException or ExecutionException reveals the underlying delegate failure.
Ensure the wrapped call is not used after the server/transport has been shut down; guard with isCancelled() and lifecycle checks.
Avoid interrupting gRPC server threads; if interruption is expected (shutdown), catch and restore the interrupt flag in your service code.
Verify the interceptor is only applied where responses must be serialized (transmitting StatusRuntimeException in trailers) and not to calls that fail on closed transports.

Example fix

// before
if (call.isReady()) { call.sendMessage(msg); }
// after
try {
  if (call.isReady()) { call.sendMessage(msg); }
} catch (RuntimeException e) {
  if (e.getCause() instanceof InterruptedException) {
    Thread.currentThread().interrupt(); // restore interrupt status
  } else {
    throw e;
  }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// check call lifecycle before reading state
if (call.isCancelled()) return;

Type guard

boolean isCallUsable(ServerCall<?,?> call) {
  try { call.isCancelled(); return true; } catch (RuntimeException e) { return false; }
}

Try / catch

try {
  boolean ready = call.isReady();
} catch (RuntimeException e) {
  Throwable cause = e.getCause();
  if (cause instanceof InterruptedException) {
    Thread.currentThread().interrupt();
  } // else: transport failure, abort the stream
}

Prevention

Do not interrupt gRPC server handler threads; use Server.shutdown() for graceful teardown.
Avoid calling ServerCall methods from inside the serializing executor.
Capture call state early in the handler before transports can tear down.
Always unwrap getCause() to find the real failure.

When it happens

Trigger: Calling isReady() on a ServerCall wrapped by TransmitStatusRuntimeExceptionInterceptor.intercept() while the underlying delegate's isReady() throws (e.g., transport already closed/failed), or the current thread is interrupted while waiting for the serializing executor to run the task.

Common situations: Server transport torn down concurrently while a service implementation checks call.isReady(); deadlocks or executor shutdown causing ExecutionException; spurious thread interruption during shutdown of a gRPC server.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/2d38c6c386c24bac. Report an issue: GitHub.