{"record":{"id":"63dcacbc166b0766","repo":"grpc/grpc-java","slug":"tls-certificate-provider-instance-is-unset","errorCode":null,"errorMessage":"tls_certificate_provider_instance is unset","messagePattern":"tls_certificate_provider_instance is unset","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsClusterResource.java","lineNumber":469,"sourceCode":"    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\n          || !CommonTlsContextUtil.isUsingSystemRootCerts(commonTlsContext))) {\n        throw new ResourceInvalidException(\n            \"ca_certificate_provider_instance or system_root_certs is required in \"\n                + \"upstream-tls-context\");","sourceCodeStart":451,"sourceCodeEnd":487,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L451-L487","documentation":"For a client-side (upstream) TLS context with no tls_certificate_provider_instance, providing inline tls_certificates is not allowed: gRPC xDS only supports identity certs via certificate provider instances, never inline material. The resource is rejected.","triggerScenarios":"server=false, certInstanceName is null, and commonTlsContext.getTlsCertificatesCount() > 0 (inline TLS certs present in the upstream_tls_context's common_tls_context).","commonSituations":"Envoy-style config with inline tls_certificates reused for gRPC; static PEM material embedded in the CDS resource; control planes that do not implement gRPC's certificate provider instance model.","solutions":["Remove the inline tls_certificates list from common_tls_context.","Provide identity certificates through tls_certificate_provider_instance configured in the gRPC bootstrap file.","If certs must be static, configure a file-based certificate provider instance (file_watcher) in the bootstrap instead of embedding PEMs in xDS."],"exampleFix":"// before\n\"common_tls_context\": {\n  \"tls_certificates\": [ { \"certificate_chain\": { \"filename\": \"cert.pem\" }, \"private_key\": { \"filename\": \"key.pem\" } } ]\n}\n// after\n\"common_tls_context\": { \"tls_certificate_provider_instance\": \"my-instance\" }","handlingStrategy":"validation","validationCode":"if (!isServerContext && commonTlsContext.getTlsCertificatesCount() > 0\n    && !commonTlsContext.hasTlsCertificateProviderInstance()) {\n  throw new IllegalArgumentException(\"inline tls_certificates unsupported; use a provider instance\");\n}","typeGuard":null,"tryCatchPattern":"catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"tls_certificate_provider_instance is unset\")) {\n    // switch resource to provider-instance-based certs\n  }\n}","preventionTips":["Never embed PEM material in CDS resources for gRPC consumers.","Use a file_watcher certificate provider for static certs instead."],"tags":["grpc","xds","tls","certificates"],"backgroundTag":"unsupported-config-value","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"}