cilium/cilium · warning

PatchEndpointIDLabelsNotFoundCode

PatchEndpointIDLabelsNotFoundCode

Error message

Endpoint ID %s not found

What it means

Returned by ModifyEndpointIdentityLabelsFromAPI when the endpoint manager's Lookup(id) finds no endpoint for the given ID (returns nil,nil). The API distinguishes 'not found' (this error, PatchEndpointIDLabelsNotFoundCode) from an invalid/malformed ID (PatchEndpointIDInvalidCode). It means the endpoint has been deleted or never existed on this node.

Source

Thrown at pkg/endpoint/api/endpoint_api_manager.go:535

// The `add` labels take precedence over `del` labels, this means if the same
// label is set on both `add` and `del`, that specific label will exist in the
// endpoint's labels.
// Returns an HTTP response code and an error msg (or nil on success).
func (m *endpointAPIManager) ModifyEndpointIdentityLabelsFromAPI(id string, add, del labels.Labels) (int, error) {
	addLabels, _ := labelsfilter.Filter(add)
	delLabels, _ := labelsfilter.Filter(del)
	if lbls := addLabels.FindReserved(); lbls != nil {
		return PatchEndpointIDLabelsUpdateFailedCode, fmt.Errorf("Not allowed to add reserved labels: %s", lbls)
	} else if lbls := delLabels.FindReserved(); lbls != nil {
		return PatchEndpointIDLabelsUpdateFailedCode, fmt.Errorf("Not allowed to delete reserved labels: %s", lbls)
	}

	ep, err := m.endpointManager.Lookup(id)
	if err != nil {
		return PatchEndpointIDInvalidCode, err
	}
	if ep == nil {
		return PatchEndpointIDLabelsNotFoundCode, fmt.Errorf("Endpoint ID %s not found", id)
	}
	if err = endpoint.APICanModify(ep); err != nil {
		return PatchEndpointIDInvalidCode, err
	}

	if err := ep.ModifyIdentityLabels(labels.LabelSourceAny, addLabels, delLabels, 0); err != nil {
		return PatchEndpointIDLabelsNotFoundCode, err
	}

	return PatchEndpointIDLabelsOKCode, nil
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Re-fetch the endpoint list (GET /endpoints) and confirm the ID exists before patching
2. Treat the 404-style response code as expected: delete/recreate the endpoint or re-derive its ID
3. Verify you are calling the agent running on the node hosting the endpoint
4. Check agent logs for endpoint deletion around the time of the call

Example fix

// before
cli.EndpointPatchLabels(ctx, "1234", add, del) // stale ID
// after
eps, _ := cli.EndpointList(ctx)
for _, ep := range eps {
    if ep.ID == targetID {
        cli.EndpointPatchLabels(ctx, targetID, add, del)
    }
}

eps, err := client.EndpointList(ctx)
if err != nil { return err }
found := false
for _, ep := range eps {
    if strconv.FormatInt(int64(ep.ID), 10) == id { found = true; break }
}
if !found { return fmt.Errorf("endpoint %s not present on this agent", id) }

err := m.ModifyEndpointIdentityLabelsFromAPI(ctx, id, add, del)
var apiErr *api.Error
if errors.As(err, &apiErr) && apiErr.Code == PatchEndpointIDLabelsNotFoundCode {
    // refresh endpoint ID and retry once
}

When it happens

Trigger: A PATCH /endpoints/{id}/labels API call with an endpoint ID that does not exist locally, e.g. after the endpoint was deleted, the agent restarted with empty state, or the ID belongs to a different node.

Common situations: Race between a client caching endpoint IDs and Cilium deleting/regenerating the endpoint; querying the wrong agent (endpoint is on another node); stale automation scripts referencing old IDs after a Cilium restart.

Related errors

• endpoint not found
• PatchEndpointIDFailedCode
• unable to parse endpoint parameters: %w
• endpoint ID %d already exists
• DeleteIpamIPFailureCode

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/0bf7b98754c8c855. Report an issue: GitHub.