{"record":{"id":"2aa455b7db06235b","repo":"grpc/grpc-java","slug":"ca-certificate-provider-instance-or-system-root-ce","errorCode":null,"errorMessage":"ca_certificate_provider_instance or system_root_certs is required in upstream-tls-context","messagePattern":"ca_certificate_provider_instance or system_root_certs is required in upstream-tls-context","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsClusterResource.java","lineNumber":485,"sourceCode":"      }\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;\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) {","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L467-L503","documentation":"A client-side (upstream) TLS context must have a root of trust: either a ca_certificate_provider_instance or explicit use of system root certs. When getRootCertInstanceName returns null and system root certs are neither enabled nor applicable, the resource is rejected.","triggerScenarios":"server=false, rootCaInstanceName is null, and either enableSystemRootCerts is false or CommonTlsContextUtil.isUsingSystemRootCerts(commonTlsContext) is false (no validation_context.combined wildcard/empty trusted_ca indicating system roots).","commonSituations":"Upstream TLS context that supplies identity certs but no CA validation source; bootstraps where system_root_certs is disabled; resources migrated from an Envoy setup that trusted a proxy's CA via SDS.","solutions":["Set a ca_certificate_provider_instance in common_tls_context naming a bootstrap-defined provider with the CA cert.","Enable system root certs and make the common_tls_context opt into them (empty validation_context / system root cert usage per gRFC A-65 style config).","Use validation_context.trusted_ca inline if your control plane supports it for the client path."],"exampleFix":"// before\n\"common_tls_context\": { \"tls_certificate_provider_instance\": \"identity-only\" }\n// after\n\"common_tls_context\": {\n  \"tls_certificate_provider_instance\": \"google_cloud_private_spiffe\",\n  \"combined_validation_context\": { \"default_validation_context\": { \"match_subject_alt_names\": [ ... ] }, \"validation_context_sds_secret_config\": { \"name\": \"ROOTCA\" } }\n}","handlingStrategy":"validation","validationCode":"if (!isServerContext && !commonTlsContext.hasCaCertificateProviderInstance()\n    && !CommonTlsContextUtil.isUsingSystemRootCerts(commonTlsContext)) {\n  throw new IllegalArgumentException(\"upstream-tls-context needs a CA provider or system roots\");\n}","typeGuard":null,"tryCatchPattern":"catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"ca_certificate_provider_instance or system_root_certs\")) {\n    // add CA provider or enable system root certs\n  }\n}","preventionTips":["Decide the root-of-trust strategy (provider instance vs system roots) before authoring upstream TLS contexts.","Enable system_root_certs in the bootstrap if clusters rely on public CAs."],"tags":["grpc","xds","tls","root-ca"],"backgroundTag":"missing-required-config-field","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}