{"record":{"id":"f78a4d7475186f7b","repo":"grpc/grpc-java","slug":"ca-certificate-provider-instance-name-rootcains","errorCode":null,"errorMessage":"ca_certificate_provider_instance name '${rootCaInstanceName}' not defined in the bootstrap file.","messagePattern":"ca_certificate_provider_instance name '(.+?)' not defined in the bootstrap file\\.","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsClusterResource.java","lineNumber":491,"sourceCode":"        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is unset\");\n      }\n    } else if (certProviderInstances == null || !certProviderInstances.contains(certInstanceName)) {\n      throw new ResourceInvalidException(\n          \"CertificateProvider instance name '\" + certInstanceName\n              + \"' not defined in the bootstrap file.\");\n    }\n    String rootCaInstanceName = getRootCertInstanceName(commonTlsContext);\n    if (rootCaInstanceName == null) {\n      if (!server && (!enableSystemRootCerts\n          || !CommonTlsContextUtil.isUsingSystemRootCerts(commonTlsContext))) {\n        throw new ResourceInvalidException(\n            \"ca_certificate_provider_instance or system_root_certs is required in \"\n                + \"upstream-tls-context\");\n      }\n    } else {\n      if (certProviderInstances == null || !certProviderInstances.contains(rootCaInstanceName)) {\n        throw new ResourceInvalidException(\n            \"ca_certificate_provider_instance name '\" + rootCaInstanceName\n                + \"' not defined in the bootstrap file.\");\n      }\n      CertificateValidationContext certificateValidationContext = null;\n      if (commonTlsContext.hasValidationContext()) {\n        certificateValidationContext = commonTlsContext.getValidationContext();\n      } else if (commonTlsContext.hasCombinedValidationContext() && commonTlsContext\n          .getCombinedValidationContext().hasDefaultValidationContext()) {\n        certificateValidationContext = commonTlsContext.getCombinedValidationContext()\n            .getDefaultValidationContext();\n      }\n      if (certificateValidationContext != null) {\n        @SuppressWarnings(\"deprecation\") // gRFC A29 predates match_typed_subject_alt_names\n        int matchSubjectAltNamesCount = certificateValidationContext.getMatchSubjectAltNamesCount();\n        if (matchSubjectAltNamesCount > 0 && server) {\n          throw new ResourceInvalidException(\n              \"match_subject_alt_names only allowed in upstream_tls_context\");\n        }","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L473-L509","documentation":"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.","triggerScenarios":"rootCaInstanceName != null but certProviderInstances is null or lacks rootCaInstanceName during validateCommonTlsContext (XdsClusterResource.java:491).","commonSituations":"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.","solutions":["Add the missing root-CA provider instance to certificate_providers in the gRPC bootstrap file.","Correct the instance name in the xDS resource to match the bootstrap key exactly.","Ensure the same bootstrap file is used consistently by the control plane's expectations and the client process."],"exampleFix":"// before (bootstrap.json certificate_providers)\n{ \"identity\": { \"plugin\": \"file_watcher\", \"config\": { ... } } }\n// after\n{\n  \"identity\": { \"plugin\": \"file_watcher\", \"config\": { ... } },\n  \"roots\": { \"plugin\": \"file_watcher\", \"config\": { \"ca_certificate_file\": \"ca.pem\" } }\n}","handlingStrategy":"validation","validationCode":"Set<String> defined = bootstrap.certProviders().keySet();\nif (rootCaInstanceName != null && !defined.contains(rootCaInstanceName)) {\n  throw new IllegalArgumentException(\"CA provider instance not in bootstrap: \" + rootCaInstanceName);\n}","typeGuard":null,"tryCatchPattern":"catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"ca_certificate_provider_instance name\")) {\n    logger.severe(\"Register CA provider in bootstrap: \" + e.getMessage());\n  }\n}","preventionTips":["Register both identity and root-CA providers in the bootstrap whenever mTLS is used.","Run bootstrap validation in CI so missing provider keys fail before deployment."],"tags":["grpc","xds","tls","bootstrap","certificate-provider"],"backgroundTag":"resource-not-found","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}