grpc/grpc-java · error · ResourceInvalidException

FilterChain ${filterChainName} with filter ${l4Filter.getNam

Error message

FilterChain ${filterChainName} with filter ${l4Filter.getName()} failed to unpack message

What it means

Although phrased generically, this exact string is thrown when the filter chain's transport_socket typed_config cannot be unpacked into an Envoy DownstreamTlsContext proto (InvalidProtocolBufferException from Any.unpack). The TLS context bytes do not match the expected protobuf type.

Source

Thrown at xds/src/main/java/io/grpc/xds/XdsListenerResource.java:263

              + " with unsupported typed_config type " + any.getTypeUrl());
    }

    // Parse HCM.
    HttpConnectionManager hcmProto;
    try {
      hcmProto = any.unpack(HttpConnectionManager.class);
    } catch (InvalidProtocolBufferException e) {
      throw new ResourceInvalidException("FilterChain " + filterChainName + " with filter "
          + l4Filter.getName() + " failed to unpack message", e);
    }
    io.grpc.xds.HttpConnectionManager httpConnectionManager = parseHttpConnectionManager(
        hcmProto, filterRegistry, false /* isForClient */, args);

    // Parse Transport Socket.
    EnvoyServerProtoData.DownstreamTlsContext downstreamTlsContext = null;
    if (proto.hasTransportSocket()) {
      if (!TRANSPORT_SOCKET_NAME_TLS.equals(proto.getTransportSocket().getName())) {
        throw new ResourceInvalidException("transport-socket with name "
            + proto.getTransportSocket().getName() + " not supported.");
      }
      DownstreamTlsContext downstreamTlsContextProto;
      try {
        downstreamTlsContextProto =
            proto.getTransportSocket().getTypedConfig().unpack(DownstreamTlsContext.class);
      } catch (InvalidProtocolBufferException e) {
        throw new ResourceInvalidException("FilterChain " + filterChainName
            + " failed to unpack message", e);
      }
      downstreamTlsContext =
          EnvoyServerProtoData.DownstreamTlsContext.fromEnvoyProtoDownstreamTlsContext(
              validateDownstreamTlsContext(downstreamTlsContextProto, certProviderInstances));
    }

    // Parse FilterChainMatch.
    FilterChainMatch filterChainMatch = parseFilterChainMatch(proto.getFilterChainMatch());
    // null used to skip this check for defaultFilterChain.

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Ensure transport_socket.typed_config contains a correctly serialized envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext with a matching v3 type_url
2. Align the management server's proto versions with the gRPC xDS library (both on v3 Envoy APIs)
3. Enable xDS client debug logging to inspect the raw Any payload and verify the type_url/bytes pair

Example fix

// before
typed_config:
  '@type': type.googleapis.com/envoy.api.v2.auth.DownstreamTlsContext
// after
typed_config:
  '@type': type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext

if (fc.hasTransportSocket()
    && !fc.getTransportSocket().getTypedConfig().getTypeUrl()
        .endsWith("tls.v3.DownstreamTlsContext")) {
  throw new IllegalArgumentException("Unexpected transport socket type_url");
}

try {
  listener = XdsListenerResource.parseServerSideListener(proto, ...);
} catch (ResourceInvalidException e) {
  if (e.getMessage().contains("failed to unpack message")) {
    logger.warn("Transport socket typed_config bytes do not match v3 DownstreamTlsContext", e);
  }
}

When it happens

Trigger: transport_socket.typed_config holds bytes that are not a valid DownstreamTlsContext for its type_url - e.g. wrong type_url with serialized data of another message, truncated payload, or mismatched proto versions - while parseFilterChain processes proto.hasTransportSocket().

Common situations: Control planes emitting v2 TLS context protos under a v3 type_url; corrupted or hand-crafted Any payloads; proto schema drift between the management server and the gRPC xDS library version.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• common-tls-context is required in upstream-tls-context
• common-tls-context with custom_handshaker is not supported
• common-tls-context with tls_params is not supported
• common-tls-context with validation_context_sds_secret_config
• tls_certificate_provider_instance is required in downstream-

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