grpc/grpc-java · error · ResourceInvalidException

CertificateProvider instance name '${certInstanceName}' not

Error message

CertificateProvider instance name '${certInstanceName}' not defined in the bootstrap file.

What it means

The tls_certificate_provider_instance (or root CA provider) named in the resource is not registered in the gRPC bootstrap file's certificate_providers map. gRPC resolves all cert material through bootstrap-declared instances, so an unknown name invalidates the resource.

Source

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

      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");
      }
    } else {
      if (certProviderInstances == null || !certProviderInstances.contains(rootCaInstanceName)) {
        throw new ResourceInvalidException(
            "ca_certificate_provider_instance name '" + rootCaInstanceName
                + "' not defined in the bootstrap file.");
      }
      CertificateValidationContext certificateValidationContext = null;

View on GitHub (pinned to 64daddc1f3)

Solutions

Add the named instance to certificate_providers in your gRPC xDS bootstrap JSON file.
Fix the instance name in the xDS resource to exactly match a key in the bootstrap.
Confirm the process is loading the bootstrap file you think it is (GRPC_XDS_BOOTSTRAP path / embedded config) and that certProviderInstances was parsed from it.

Example fix

// before (bootstrap.json)
{ "xds_servers": [ ... ] }
// after
{
  "xds_servers": [ ... ],
  "certificate_providers": {
    "google_cloud_private_spiffe": { "plugin": "file_watcher", "config": { "certificate_file": "cert.pem", "private_key_file": "key.pem", "ca_certificate_file": "ca.pem" } }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// before creating the resource
Set<String> defined = bootstrap.certProviders().keySet();
if (instanceName != null && !defined.contains(instanceName)) {
  throw new IllegalArgumentException("provider instance not in bootstrap: " + instanceName);
}

Try / catch

catch (ResourceInvalidException e) {
  if (e.getMessage().contains("not defined in the bootstrap file")) {
    logger.severe("Sync control-plane provider names with gRPC bootstrap: " + e.getMessage());
  }
}

Prevention

Keep a single source of truth for provider instance names shared by control plane and bootstrap.
Validate bootstrap JSON (certificate_providers keys) at service startup.
Use consistent naming conventions to avoid typos between resource and bootstrap.

When it happens

Trigger: certInstanceName != null but certProviderInstances is null or does not contain certInstanceName when validating an upstream/downstream TLS context (XdsClusterResource.java:477).

Common situations: Typo in the provider instance name; bootstrap file missing the certificate_providers section; control plane and client bootstrap out of sync after renaming instances.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

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