{"record":{"id":"b7d83cde0a72a2dd","repo":"istio/istio","slug":"proxy-metadata-indicates-that-it-must-correspond-t","errorCode":null,"errorMessage":"proxy metadata indicates that it must correspond to an existing WorkloadEntry, however WorkloadEntry %s/%s is not found","messagePattern":"proxy metadata indicates that it must correspond to an existing WorkloadEntry, however WorkloadEntry (.+?)/(.+?) is not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pilot/pkg/autoregistration/controller.go","lineNumber":247,"sourceCode":"// If connecting proxy represents a workload that is not using auto-registration,\n// the WorkloadEntry resource is expected to exist beforehand. Otherwise, no special\n// processing will be initiated, e.g. health status updates will be ignored.\nfunc (c *Controller) OnConnect(conn connection) error {\n\tif c == nil {\n\t\treturn nil\n\t}\n\tproxy := conn.Proxy()\n\tvar entryName string\n\tvar autoCreate bool\n\tif features.WorkloadEntryAutoRegistration && proxy.Metadata.AutoRegisterGroup != \"\" {\n\t\tentryName = autoregisteredWorkloadEntryName(proxy)\n\t\tautoCreate = true\n\t} else if features.WorkloadEntryHealthChecks && proxy.Metadata.WorkloadEntry != \"\" {\n\t\t// a non-empty value of the `WorkloadEntry` field indicates that proxy must correspond to the WorkloadEntry\n\t\twle := c.store.Get(gvk.WorkloadEntry, proxy.Metadata.WorkloadEntry, proxy.Metadata.Namespace)\n\t\tif wle == nil {\n\t\t\t// either invalid proxy configuration or config propagation delay\n\t\t\treturn fmt.Errorf(\"proxy metadata indicates that it must correspond to an existing WorkloadEntry, \"+\n\t\t\t\t\"however WorkloadEntry %s/%s is not found\", proxy.Metadata.Namespace, proxy.Metadata.WorkloadEntry)\n\t\t}\n\t\tif health.IsEligibleForHealthStatusUpdates(wle) {\n\t\t\tif err := ensureProxyCanControlEntry(proxy, wle); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tentryName = wle.Name\n\t\t}\n\t}\n\tif entryName == \"\" {\n\t\treturn nil\n\t}\n\n\tproxy.SetWorkloadEntry(entryName, autoCreate)\n\tc.adsConnections.Connect(conn)\n\n\terr := c.onWorkloadConnect(entryName, proxy, conn.ConnectedAt(), autoCreate)\n\tif err != nil {","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/istio/istio/blob/8dc789c5cf17517c64e3c36cb3288230f149dfae/pilot/pkg/autoregistration/controller.go#L229-L265","documentation":"In the workload auto-registration/health-check controller, the connected proxy's metadata sets a WorkloadEntry name (proxy.Metadata.WorkloadEntry) with WorkloadEntryHealthChecks enabled, meaning the proxy must map onto an existing WorkloadEntry — but the store lookup for namespace/name returns nil. The comment itself names the two causes: invalid proxy configuration, or config propagation delay (the entry exists but this istiod has not seen it yet).","triggerScenarios":"A proxy connects (xDS connection) with ISTIO_META WorkloadEntry metadata pointing at an entry that does not exist in that istiod's config store — wrong name/namespace in metadata, entry deleted, or entry created moments ago and not yet propagated (multi-cluster/read-replica store lag).","commonSituations":"VM/physical workload configured with a WorkloadEntry name typo or wrong namespace; entry created right after the workload connects so the first connections fail; entry deleted but the proxy keeps its metadata; multi-cluster control planes where the entry lives in another cluster's store.","solutions":["Verify the WorkloadEntry exists: kubectl get workloadentry -n <namespace> <name> and compare against the proxy's metadata exactly","If it was just created, simply reconnect/wait — the proxy's next connection re-runs onWorkloadConnect and succeeds once the store catches up","Fix the proxy's WorkloadEntry metadata (name and namespace must match the resource) and reconnect","If you never intended health-check association, clear the WorkloadEntry metadata field on the proxy"],"exampleFix":"# before: proxy metadata points at a nonexistent entry\n#   ISTIO_META_WORKLOAD_ENTRY=my-workload   (entry is actually named my-workload-vm)\nkubectl get workloadentries -n default my-workload   # NotFound -> error on connect\n# after\n#   ISTIO_META_WORKLOAD_ENTRY=my-workload-vm\nkubectl get workloadentries -n default my-workload-vm # found; connect succeeds","handlingStrategy":"retry","validationCode":"// Before pointing a proxy at a WorkloadEntry, confirm it is visible\nif _, err := k8s.NetworkingV1().WorkloadEntries(ns).Get(ctx, entryName, metav1.GetOptions{}); err != nil {\n    return fmt.Errorf(\"create WorkloadEntry %s/%s before starting the workload: %w\", ns, entryName, err)\n}","typeGuard":null,"tryCatchPattern":"// Proxy/bootstrap side: connection-time failure is retryable propagation lag\nif err := connectXDS(); err != nil && strings.Contains(err.Error(), \"WorkloadEntry\") && strings.Contains(err.Error(), \"not found\") {\n    time.Sleep(retryInterval) // entry may still be propagating; next xDS attempt retries\n    continue\n}","preventionTips":["Create the WorkloadEntry before booting the VM/workload that references it","Generate the entry name and the proxy metadata from one source of truth","Prefer auto-registration (AutoRegisterGroup) so entries cannot be missing"],"tags":["istio","workloadentry","virtual-machines","autoregistration","xds","configuration"],"backgroundTag":null,"analyzedSha":"8dc789c5cf17517c64e3c36cb3288230f149dfae","analyzedAt":"2026-08-15T15:16:55.434Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}