grpc/grpc-java · error · ResourceInvalidException

common-tls-context with validation_context_sds_secret_config

Error message

common-tls-context with validation_context_sds_secret_config is not supported

What it means

validation_context_sds_secret_config (a SecretDiscoveryService-based validation context) is not supported by the gRPC xDS client; only inline validation_context, combined_validation_context, or a certificate provider instance root are allowed. Presence of this field invalidates the cluster resource.

Source

Thrown at xds/src/main/java/io/grpc/xds/XdsClusterResource.java:459

    } else {
      throw new ResourceInvalidException("common-tls-context is required in upstream-tls-context");
    }
    return upstreamTlsContext;
  }

  @VisibleForTesting
  static void validateCommonTlsContext(
      CommonTlsContext commonTlsContext, Set<String> certProviderInstances, boolean server)
      throws ResourceInvalidException {
    if (commonTlsContext.hasCustomHandshaker()) {
      throw new ResourceInvalidException(
          "common-tls-context with custom_handshaker is not supported");
    }
    if (commonTlsContext.hasTlsParams()) {
      throw new ResourceInvalidException("common-tls-context with tls_params is not supported");
    }
    if (commonTlsContext.hasValidationContextSdsSecretConfig()) {
      throw new ResourceInvalidException(
          "common-tls-context with validation_context_sds_secret_config is not supported");
    }
    String certInstanceName = getIdentityCertInstanceName(commonTlsContext);
    if (certInstanceName == null) {
      if (server) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is required in downstream-tls-context");
      }
      if (commonTlsContext.getTlsCertificatesCount() > 0) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is unset");
      }
      if (commonTlsContext.getTlsCertificateSdsSecretConfigsCount() > 0) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is unset");
      }
    } else if (certProviderInstances == null || !certProviderInstances.contains(certInstanceName)) {
      throw new ResourceInvalidException(

View on GitHub (pinned to 64daddc1f3)

Solutions

Replace validation_context_sds_secret_config with an inline validation_context carrying trusted_ca.
Use combined_validation_context with a default_validation_context and a certificate_provider_instance for root certs.
Point the control plane at gRPC-supported config (certificate provider instances from the gRPC bootstrap) instead of SDS secrets.

Example fix

// before
"common_tls_context": {
  "validation_context_sds_secret_config": { "name": "validation-context-sds" }
}
// after
"common_tls_context": {
  "validation_context": { "trusted_ca": { "filename": "/etc/certs/ca.pem" } }
}

Defensive patterns

Strategy: validation

Validate before calling

if (commonTlsContext.hasValidationContextSdsSecretConfig()) {
  throw new IllegalArgumentException("use inline validation_context instead of SDS secret config");
}

Try / catch

catch (ResourceInvalidException e) {
  if (e.getMessage().contains("validation_context_sds_secret_config")) {
    // regenerate resource with inline trusted_ca
  }
}

Prevention

Prefer validation_context or combined_validation_context in all gRPC-targeted resources.
Reserve SDS secrets for Envoy-only clusters, not clusters consumed by gRPC xDS clients.

When it happens

Trigger: A common_tls_context inside upstream_tls_context/downstream_tls_context sets validation_context_sds_secret_config referencing an SDS secret name. validateCommonTlsContext throws ResourceInvalidException at XdsClusterResource.java:459.

Common situations: Envoy deployments that distribute CA certs via SDS secrets and reuse the same resources for gRPC clients; control planes (e.g. some Istio/Envoy-generated configs) that always emit SDS-based validation contexts.

Understand the failure class

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/5a643039b49cabcc. Report an issue: GitHub.