{"record":{"id":"d35668706933c87e","repo":"grpc/grpc-java","slug":"tls-version-d-is-not-supported","errorCode":null,"errorMessage":"TLS version %d is not supported.","messagePattern":"TLS version (.+?) is not supported\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"s2a/src/main/java/io/grpc/s2a/internal/handshaker/ProtoUtil.java","lineNumber":46,"sourceCode":"   *\n   * @param tlsVersion the {@link TLSVersion} object to be converted.\n   * @return a {@link String} representation of the TLS version.\n   * @throws IllegalArgumentException if the {@code tlsVersion} is not one of\n   *     the supported TLS versions.\n   */\n  @VisibleForTesting\n  static String convertTlsProtocolVersion(TLSVersion tlsVersion) {\n    switch (tlsVersion) {\n      case TLS_VERSION_1_3:\n        return \"TLSv1.3\";\n      case TLS_VERSION_1_2:\n        return \"TLSv1.2\";\n      case TLS_VERSION_1_1:\n        return \"TLSv1.1\";\n      case TLS_VERSION_1_0:\n        return \"TLSv1\";\n      default:\n        throw new IllegalArgumentException(\n            String.format(\"TLS version %d is not supported.\", tlsVersion.getNumber()));\n    }\n  }\n\n  /**\n   * Builds a set of strings representing all {@link TLSVersion}s between {@code minTlsVersion} and\n   * {@code maxTlsVersion}.\n   */\n  static ImmutableSet<String> buildTlsProtocolVersionSet(\n      TLSVersion minTlsVersion, TLSVersion maxTlsVersion) {\n    ImmutableSet.Builder<String> tlsVersions = ImmutableSet.<String>builder();\n    for (TLSVersion tlsVersion : TLSVersion.values()) {\n      int versionNumber;\n      try {\n        versionNumber = tlsVersion.getNumber();\n      } catch (IllegalArgumentException e) {\n        continue;\n      }","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/s2a/src/main/java/io/grpc/s2a/internal/handshaker/ProtoUtil.java#L28-L64","documentation":"convertTlsProtocolVersion maps S2A handshaker protobuf TLSVersion enum values to Java TLS protocol-name strings. The default branch throws this IllegalArgumentException when the proto enum carries a value outside the supported set (TLS 1.0/1.1/1.2), typically because the S2A handshaker server sent an enum value this client build does not know (e.g. TLS 1.3 in an older client).","triggerScenarios":"Calling buildTlsProtocolVersionSet (invoked during S2A channel setup) with min/max TLS versions where a version is TLS_VERSION_UNSPECIFIED, out-of-range, or a newer enum constant (e.g. TLS_VERSION_1_3) unrecognized by the mapped switch in this client version.","commonSituations":"S2A server upgraded to support TLS 1.3 while the gRPC s2a client library predates that enum value; misconfigured S2A policy returning TLS_VERSION_UNSPECIFIED; version skew between handshaker proto files.","solutions":["Upgrade the gRPC s2a client/handshaker library to a version whose proto and mapping include the TLS version S2A returns.","Constrain the S2A policy's min/max TLS versions to 1.0–1.2 (ideally just TLS 1.2) until versions are aligned.","Check the handshaker proto: ensure both sides are generated from the same tls.proto version so enum numbers match.","Log tlsVersion.getNumber() on failure to identify the offending enum value and confirm the diagnosis."],"exampleFix":"// before (older client)\nmin_tls_version: TLS_VERSION_1_3\n// after\nmin_tls_version: TLS_VERSION_1_2  // or upgrade client library to support TLS 1.3","handlingStrategy":"validation","validationCode":"static void checkSupportedTlsVersion(TLSVersion v) {\n  switch (v) {\n    case TLS_VERSION_1_0:\n    case TLS_VERSION_1_1:\n    case TLS_VERSION_1_2:\n      return;\n    default:\n      throw new IllegalArgumentException(\"TLS version \" + v.getNumber() + \" unsupported by client\");\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin min/max TLS versions to values the client library maps (ideally 1.2 only).","Keep s2a client and handshaker proto versions in lockstep with the S2A service.","Prefer TLS 1.2/1.3 policy consistently; never send TLS_VERSION_UNSPECIFIED.","Log the raw enum number on unsupported values to detect version skew fast."],"tags":["grpc","s2a","tls","enum"],"backgroundTag":"unsupported-enum-value","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}