{"record":{"id":"15b243caea629e87","repo":"grpc/grpc-java","slug":"tls-certificate-provider-instance-is-required-in-d","errorCode":null,"errorMessage":"tls_certificate_provider_instance is required in downstream-tls-context","messagePattern":"tls_certificate_provider_instance is required in downstream-tls-context","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsClusterResource.java","lineNumber":465,"sourceCode":"  @VisibleForTesting\n  static void validateCommonTlsContext(\n      CommonTlsContext commonTlsContext, Set<String> certProviderInstances, boolean server)\n      throws ResourceInvalidException {\n    if (commonTlsContext.hasCustomHandshaker()) {\n      throw new ResourceInvalidException(\n          \"common-tls-context with custom_handshaker is not supported\");\n    }\n    if (commonTlsContext.hasTlsParams()) {\n      throw new ResourceInvalidException(\"common-tls-context with tls_params is not supported\");\n    }\n    if (commonTlsContext.hasValidationContextSdsSecretConfig()) {\n      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","sourceCodeStart":447,"sourceCodeEnd":483,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L447-L483","documentation":"For server-side (downstream) TLS contexts, a tls_certificate_provider_instance is mandatory: the server must obtain its identity certificate from a certificate provider defined in the gRPC bootstrap file. When none is present, validateCommonTlsContext rejects the resource.","triggerScenarios":"validateCommonTlsContext is called with server=true (e.g. a listener's downstream_tls_context) and getIdentityCertInstanceName(commonTlsContext) returns null because no certificate_provider_instance is set.","commonSituations":"Configuring xDS server-side mTLS without provisioning identity certs; bootstraps missing the certificate_providers section; copying client-only TLS config to a server listener.","solutions":["Set tls_certificate_provider_instance in common_tls_context with a name defined in the gRPC bootstrap's certificate_providers map.","Add a certificate provider (e.g. file-watcher or mesh-ca) to the bootstrap file for the referenced instance name.","If server TLS is managed outside gRPC, use non-xDS ServerCredentials instead of xDS-provided downstream TLS."],"exampleFix":"// before\n\"common_tls_context\": { \"validation_context\": { ... } }\n// after\n\"common_tls_context\": {\n  \"tls_certificate_provider_instance\": \"google_cloud_private_spiffe\",\n  \"validation_context\": { ... }\n}","handlingStrategy":"validation","validationCode":"if (isServerContext && !commonTlsContext.hasTlsCertificateProviderInstance()) {\n  throw new IllegalArgumentException(\"downstream-tls-context needs tls_certificate_provider_instance\");\n}","typeGuard":null,"tryCatchPattern":"catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"required in downstream-tls-context\")) {\n    logger.severe(\"Add a certificate provider instance to server TLS config\");\n  }\n}","preventionTips":["Define certificate_providers in the gRPC bootstrap before enabling server-side xDS TLS.","Always pair server listener configs with an identity cert provider instance."],"tags":["grpc","xds","tls","server","mtls"],"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-14T05:17:10.506Z"}