What causes "Can't set TLS settings for ALTS" in grpc/grpc-java?

Remove the useTransportSecurity() call — ALTS negotiates its own channel encryption

grpc/grpc-java · error · UnsupportedOperationException

Can't set TLS settings for ALTS

Error message

Can't set TLS settings for ALTS

What it means

AltsServerBuilder deliberately does not support configuring TLS via useTransportSecurity(), because ALTS provides its own transport security layer. Any attempt to set TLS certs on an ALTS server throws UnsupportedOperationException at build time.

Source

Thrown at alts/src/main/java/io/grpc/alts/AltsServerBuilder.java:136

  /** {@inheritDoc} */
  @Override
  public AltsServerBuilder addService(BindableService bindableService) {
    delegate.addService(bindableService);
    return this;
  }

  /** {@inheritDoc} */
  @Override
  public AltsServerBuilder fallbackHandlerRegistry(HandlerRegistry fallbackRegistry) {
    delegate.fallbackHandlerRegistry(fallbackRegistry);
    return this;
  }

  /** {@inheritDoc} */
  @Override
  public AltsServerBuilder useTransportSecurity(File certChain, File privateKey) {
    throw new UnsupportedOperationException("Can't set TLS settings for ALTS");
  }

  /** {@inheritDoc} */
  @Override
  public AltsServerBuilder decompressorRegistry(DecompressorRegistry registry) {
    delegate.decompressorRegistry(registry);
    return this;
  }

  /** {@inheritDoc} */
  @Override
  public AltsServerBuilder compressorRegistry(CompressorRegistry registry) {
    delegate.compressorRegistry(registry);
    return this;
  }

  /** {@inheritDoc} */
  @Override

View on GitHub (pinned to 64daddc1f3)

Solutions

Remove the useTransportSecurity() call — ALTS negotiates its own channel encryption
If TLS is genuinely required, use NettyServerBuilder/GrpcSslContexts instead of AltsServerBuilder
Keep a single builder code path and branch on the transport type instead of calling transport-specific methods

Example fix

// before
AltsServerBuilder.forPort(port).useTransportSecurity(cert, key).addService(svc).build();
// after
AltsServerBuilder.forPort(port).addService(svc).build(); // ALTS handles transport security

Defensive patterns

Strategy: validation

Validate before calling

if (builder instanceof AltsServerBuilder) {
  throw new IllegalStateException("Do not configure TLS; ALTS provides transport security");
}

Type guard

null

Try / catch

try {
  builder.useTransportSecurity(cert, key);
} catch (UnsupportedOperationException e) {
  // ALTS builder: skip TLS config; switch to NettyServerBuilder if TLS is required
}

Prevention

Never copy TLS-config code into ALTS builder chains
Abstract server construction so TLS options only apply to TLS-capable builders
Remember ALTS already encrypts the transport

When it happens

Trigger: Calling useTransportSecurity(certChain, privateKey) on an AltsServerBuilder instance, typically by copy-pasting builder code written for NettyServerBuilder.

Common situations: Migrating a Netty server to ALTS while leaving the TLS configuration lines in place; or shared builder-factory code that configures TLS for all server types.

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/8c9faccb88e14f52. Report an issue: GitHub.