proxy metadata indicates that it must correspond to an exist

Error message

proxy metadata indicates that it must correspond to an existing WorkloadEntry, however WorkloadEntry %s/%s is not found

What it means

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).

Source

Thrown at pilot/pkg/autoregistration/controller.go:247

// If connecting proxy represents a workload that is not using auto-registration,
// the WorkloadEntry resource is expected to exist beforehand. Otherwise, no special
// processing will be initiated, e.g. health status updates will be ignored.
func (c *Controller) OnConnect(conn connection) error {
	if c == nil {
		return nil
	}
	proxy := conn.Proxy()
	var entryName string
	var autoCreate bool
	if features.WorkloadEntryAutoRegistration && proxy.Metadata.AutoRegisterGroup != "" {
		entryName = autoregisteredWorkloadEntryName(proxy)
		autoCreate = true
	} else if features.WorkloadEntryHealthChecks && proxy.Metadata.WorkloadEntry != "" {
		// a non-empty value of the `WorkloadEntry` field indicates that proxy must correspond to the WorkloadEntry
		wle := c.store.Get(gvk.WorkloadEntry, proxy.Metadata.WorkloadEntry, proxy.Metadata.Namespace)
		if wle == nil {
			// either invalid proxy configuration or config propagation delay
			return fmt.Errorf("proxy metadata indicates that it must correspond to an existing WorkloadEntry, "+
				"however WorkloadEntry %s/%s is not found", proxy.Metadata.Namespace, proxy.Metadata.WorkloadEntry)
		}
		if health.IsEligibleForHealthStatusUpdates(wle) {
			if err := ensureProxyCanControlEntry(proxy, wle); err != nil {
				return err
			}
			entryName = wle.Name
		}
	}
	if entryName == "" {
		return nil
	}

	proxy.SetWorkloadEntry(entryName, autoCreate)
	c.adsConnections.Connect(conn)

	err := c.onWorkloadConnect(entryName, proxy, conn.ConnectedAt(), autoCreate)
	if err != nil {

View on GitHub (pinned to 8dc789c5cf)

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

Example fix

# before: proxy metadata points at a nonexistent entry
#   ISTIO_META_WORKLOAD_ENTRY=my-workload   (entry is actually named my-workload-vm)
kubectl get workloadentries -n default my-workload   # NotFound -> error on connect
# after
#   ISTIO_META_WORKLOAD_ENTRY=my-workload-vm
kubectl get workloadentries -n default my-workload-vm # found; connect succeeds

Defensive patterns

Strategy: retry

Validate before calling

// Before pointing a proxy at a WorkloadEntry, confirm it is visible
if _, err := k8s.NetworkingV1().WorkloadEntries(ns).Get(ctx, entryName, metav1.GetOptions{}); err != nil {
    return fmt.Errorf("create WorkloadEntry %s/%s before starting the workload: %w", ns, entryName, err)
}

Try / catch

// Proxy/bootstrap side: connection-time failure is retryable propagation lag
if err := connectXDS(); err != nil && strings.Contains(err.Error(), "WorkloadEntry") && strings.Contains(err.Error(), "not found") {
    time.Sleep(retryInterval) // entry may still be propagating; next xDS attempt retries
    continue
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of istio/istio@8dc789c5cf (2026-08-15). Data as JSON: /api/errors/b7d83cde0a72a2dd. Report an issue: GitHub.