{"record":{"id":"d7dbdd58d466a2cd","repo":"grpc/grpc-java","slug":"certificateprovider-instance-name-certinstancen","errorCode":null,"errorMessage":"CertificateProvider instance name '${certInstanceName}' not defined in the bootstrap file.","messagePattern":"CertificateProvider 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":477,"sourceCode":"      throw new ResourceInvalidException(\n          \"common-tls-context with validation_context_sds_secret_config is not supported\");\n    }\n    String certInstanceName = getIdentityCertInstanceName(commonTlsContext);\n    if (certInstanceName == null) {\n      if (server) {\n        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is required in downstream-tls-context\");\n      }\n      if (commonTlsContext.getTlsCertificatesCount() > 0) {\n        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is unset\");\n      }\n      if (commonTlsContext.getTlsCertificateSdsSecretConfigsCount() > 0) {\n        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;","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L459-L495","documentation":"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.","triggerScenarios":"certInstanceName != null but certProviderInstances is null or does not contain certInstanceName when validating an upstream/downstream TLS context (XdsClusterResource.java:477).","commonSituations":"Typo in the provider instance name; bootstrap file missing the certificate_providers section; control plane and client bootstrap out of sync after renaming instances.","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."],"exampleFix":"// before (bootstrap.json)\n{ \"xds_servers\": [ ... ] }\n// after\n{\n  \"xds_servers\": [ ... ],\n  \"certificate_providers\": {\n    \"google_cloud_private_spiffe\": { \"plugin\": \"file_watcher\", \"config\": { \"certificate_file\": \"cert.pem\", \"private_key_file\": \"key.pem\", \"ca_certificate_file\": \"ca.pem\" } }\n  }\n}","handlingStrategy":"validation","validationCode":"// before creating the resource\nSet<String> defined = bootstrap.certProviders().keySet();\nif (instanceName != null && !defined.contains(instanceName)) {\n  throw new IllegalArgumentException(\"provider instance not in bootstrap: \" + instanceName);\n}","typeGuard":null,"tryCatchPattern":"catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"not defined in the bootstrap file\")) {\n    logger.severe(\"Sync control-plane provider names with gRPC bootstrap: \" + e.getMessage());\n  }\n}","preventionTips":["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."],"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"}