grpc/grpc-java · error · ResourceInvalidException

ca_certificate_provider_instance name '${rootCaInstanceName}

Error message

ca_certificate_provider_instance name '${rootCaInstanceName}' not defined in the bootstrap file.

What it means

The ca_certificate_provider_instance (root cert provider) named in the resource is not defined in the gRPC bootstrap file's certificate_providers map, mirroring the identity-cert check for error 346. gRPC requires every referenced provider instance to exist locally.

Source

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

        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;
      if (commonTlsContext.hasValidationContext()) {
        certificateValidationContext = commonTlsContext.getValidationContext();
      } else if (commonTlsContext.hasCombinedValidationContext() && commonTlsContext
          .getCombinedValidationContext().hasDefaultValidationContext()) {
        certificateValidationContext = commonTlsContext.getCombinedValidationContext()
            .getDefaultValidationContext();
      }
      if (certificateValidationContext != null) {
        @SuppressWarnings("deprecation") // gRFC A29 predates match_typed_subject_alt_names
        int matchSubjectAltNamesCount = certificateValidationContext.getMatchSubjectAltNamesCount();
        if (matchSubjectAltNamesCount > 0 && server) {
          throw new ResourceInvalidException(
              "match_subject_alt_names only allowed in upstream_tls_context");
        }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add the missing root-CA provider instance to certificate_providers in the gRPC bootstrap file.
2. Correct the instance name in the xDS resource to match the bootstrap key exactly.
3. Ensure the same bootstrap file is used consistently by the control plane's expectations and the client process.

Example fix

// before (bootstrap.json certificate_providers)
{ "identity": { "plugin": "file_watcher", "config": { ... } } }
// after
{
  "identity": { "plugin": "file_watcher", "config": { ... } },
  "roots": { "plugin": "file_watcher", "config": { "ca_certificate_file": "ca.pem" } }
}

Set<String> defined = bootstrap.certProviders().keySet();
if (rootCaInstanceName != null && !defined.contains(rootCaInstanceName)) {
  throw new IllegalArgumentException("CA provider instance not in bootstrap: " + rootCaInstanceName);
}

catch (ResourceInvalidException e) {
  if (e.getMessage().contains("ca_certificate_provider_instance name")) {
    logger.severe("Register CA provider in bootstrap: " + e.getMessage());
  }
}

When it happens

Trigger: rootCaInstanceName != null but certProviderInstances is null or lacks rootCaInstanceName during validateCommonTlsContext (XdsClusterResource.java:491).

Common situations: Root CA provider name typo; bootstrap file lacking the CA provider entry; separate instances configured for identity vs root with only one present in the bootstrap.

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

• CertificateProvider instance name '${certInstanceName}' not
• 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/f78a4d7475186f7b. Report an issue: GitHub.