grpc/grpc-java · error · ResourceInvalidException

tls_certificate_provider_instance is unset

Error message

tls_certificate_provider_instance is unset

What it means

For a client-side (upstream) TLS context with no tls_certificate_provider_instance, providing inline tls_certificates is not allowed: gRPC xDS only supports identity certs via certificate provider instances, never inline material. The resource is rejected.

Source

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

    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
          || !CommonTlsContextUtil.isUsingSystemRootCerts(commonTlsContext))) {
        throw new ResourceInvalidException(
            "ca_certificate_provider_instance or system_root_certs is required in "
                + "upstream-tls-context");

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Remove the inline tls_certificates list from common_tls_context.
2. Provide identity certificates through tls_certificate_provider_instance configured in the gRPC bootstrap file.
3. If certs must be static, configure a file-based certificate provider instance (file_watcher) in the bootstrap instead of embedding PEMs in xDS.

Example fix

// before
"common_tls_context": {
  "tls_certificates": [ { "certificate_chain": { "filename": "cert.pem" }, "private_key": { "filename": "key.pem" } } ]
}
// after
"common_tls_context": { "tls_certificate_provider_instance": "my-instance" }

if (!isServerContext && commonTlsContext.getTlsCertificatesCount() > 0
    && !commonTlsContext.hasTlsCertificateProviderInstance()) {
  throw new IllegalArgumentException("inline tls_certificates unsupported; use a provider instance");
}

catch (ResourceInvalidException e) {
  if (e.getMessage().contains("tls_certificate_provider_instance is unset")) {
    // switch resource to provider-instance-based certs
  }
}

When it happens

Trigger: server=false, certInstanceName is null, and commonTlsContext.getTlsCertificatesCount() > 0 (inline TLS certs present in the upstream_tls_context's common_tls_context).

Common situations: Envoy-style config with inline tls_certificates reused for gRPC; static PEM material embedded in the CDS resource; control planes that do not implement gRPC's certificate provider instance model.

Understand the failure class

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

Related errors

• Failed to build SSL context from certificate files: ${e}
• Failed to build SSL context from certificate streams: ${e}
• 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

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