What causes "TLS not supported in ServerImplBuilder" in grpc/grpc-java?

Use a concrete transport builder (NettyServerBuilder) and call its useTransportSecurity or sslContext with the cert chain and private key

grpc/grpc-java · error · UnsupportedOperationException

TLS not supported in ServerImplBuilder

Error message

TLS not supported in ServerImplBuilder

What it means

ServerImplBuilder is transport-agnostic and cannot wire TLS file-based transport security, which only concrete transports (netty, okhttp) can configure. Its useTransportSecurity(File,File) override therefore unconditionally throws UnsupportedOperationException.

Source

Thrown at core/src/main/java/io/grpc/internal/ServerImplBuilder.java:360

    @Nullable
    @Override
    public ServerMethodDefinition<?, ?> lookupMethod(
        String methodName, @Nullable String authority) {
      return null;
    }
  }

  /**
   * Returns the internal ExecutorPool for offloading tasks.
   */
  public ObjectPool<? extends Executor> getExecutorPool() {
    return this.executorPool;
  }

  @Override
  public ServerImplBuilder useTransportSecurity(File certChain, File privateKey) {
    throw new UnsupportedOperationException("TLS not supported in ServerImplBuilder");
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

Use a concrete transport builder (NettyServerBuilder) and call its useTransportSecurity or sslContext with the cert chain and private key
Add the grpc-netty (or other transport) dependency so the concrete builder is used
Configure TLS outside the builder (e.g. via Netty's SslContext / ProxyDetector-free TlsServerCredentials with ServerCredentials-based forPort APIs)

Example fix

// before
ServerBuilder<?> b = ServerBuilder.forPort(8080);
b.useTransportSecurity(cert, key); // UnsupportedOperationException
// after
NettyServerBuilder b = NettyServerBuilder.forPort(8080);
b.useTransportSecurity(cert, key);

Defensive patterns

Strategy: validation

Validate before calling

if (b instanceof ServerImplBuilder) { /* cannot configure TLS here; use NettyServerBuilder or ServerCredentials */ }

Type guard

static boolean supportsTls(ServerBuilder<?> b) { return !(b instanceof io.grpc.internal.ServerImplBuilder); }

Try / catch

try { b.useTransportSecurity(cert, key); } catch (UnsupportedOperationException e) { if (e.getMessage().contains("TLS not supported")) { /* rebuild with NettyServerBuilder */ } else throw e; }

Prevention

Configure TLS only on concrete transport builders or via ServerCredentials/TlsServerCredentials
Add grpc-netty before attempting transport security
Keep a single transport builder type in your server bootstrap code

When it happens

Trigger: Calling useTransportSecurity(certChain, privateKey) on a ServerImplBuilder instance — e.g. obtained when ServerBuilder.forPort/forRegistry falls back without a transport provider, or through generic ServerBuilder code resolved to ServerImplBuilder.

Common situations: Same missing grpc-netty dependency scenario as forPort: code compiles against ServerBuilder but no concrete transport builder is present; framework code applying TLS config generically.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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