grpc/grpc-java · error · ResourceInvalidException

tls_certificate_provider_instance is required in downstream-

Error message

tls_certificate_provider_instance is required in downstream-tls-context

What it means

For server-side (downstream) TLS contexts, a tls_certificate_provider_instance is mandatory: the server must obtain its identity certificate from a certificate provider defined in the gRPC bootstrap file. When none is present, validateCommonTlsContext rejects the resource.

Source

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

  @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(
          "CertificateProvider instance name '" + certInstanceName
              + "' not defined in the bootstrap file.");
    }
    String rootCaInstanceName = getRootCertInstanceName(commonTlsContext);
    if (rootCaInstanceName == null) {
      if (!server && (!enableSystemRootCerts

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Set tls_certificate_provider_instance in common_tls_context with a name defined in the gRPC bootstrap's certificate_providers map.
2. Add a certificate provider (e.g. file-watcher or mesh-ca) to the bootstrap file for the referenced instance name.
3. If server TLS is managed outside gRPC, use non-xDS ServerCredentials instead of xDS-provided downstream TLS.

Example fix

// before
"common_tls_context": { "validation_context": { ... } }
// after
"common_tls_context": {
  "tls_certificate_provider_instance": "google_cloud_private_spiffe",
  "validation_context": { ... }
}

if (isServerContext && !commonTlsContext.hasTlsCertificateProviderInstance()) {
  throw new IllegalArgumentException("downstream-tls-context needs tls_certificate_provider_instance");
}

catch (ResourceInvalidException e) {
  if (e.getMessage().contains("required in downstream-tls-context")) {
    logger.severe("Add a certificate provider instance to server TLS config");
  }
}

When it happens

Trigger: validateCommonTlsContext is called with server=true (e.g. a listener's downstream_tls_context) and getIdentityCertInstanceName(commonTlsContext) returns null because no certificate_provider_instance is set.

Common situations: Configuring xDS server-side mTLS without provisioning identity certs; bootstraps missing the certificate_providers section; copying client-only TLS config to a server listener.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

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

Related errors

• match_subject_alt_names only allowed in upstream_tls_context
• 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

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