{"record":{"id":"62f01a6e434cfd91","repo":"cilium/cilium","slug":"invalid-backend-port-annotation-q-w","errorCode":null,"errorMessage":"invalid backend-port annotation %q: %w","messagePattern":"invalid backend-port annotation %q: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"operator/pkg/gateway-api/endpointslice_reconcile.go","lineNumber":99,"sourceCode":"\tif !predicates.IsManagedFrontendEndpointSlice(frontend) {\n\t\treturn controllerruntime.Success()\n\t}\n\n\tbackendRef := frontend.Annotations[gwModel.BackendServiceAnnotation]\n\tif backendRef == \"\" {\n\t\tscopedLog.WarnContext(ctx, \"Managed EndpointSlice missing backend-service annotation, skipping\")\n\t\treturn controllerruntime.Success()\n\t}\n\tbackendNs, backendName, ok := strings.Cut(backendRef, \"/\")\n\tif !ok || backendNs == \"\" || backendName == \"\" {\n\t\tscopedLog.WarnContext(ctx, \"Invalid backend-service annotation\",\n\t\t\tlogfields.Annotation, backendRef)\n\t\treturn controllerruntime.Success()\n\t}\n\n\tservicePort, err := strconv.ParseUint(frontend.Annotations[gwModel.BackendPortAnnotation], 10, 16)\n\tif err != nil {\n\t\treturn controllerruntime.Fail(fmt.Errorf(\"invalid backend-port annotation %q: %w\",\n\t\t\tfrontend.Annotations[gwModel.BackendPortAnnotation], err))\n\t}\n\n\tbackendSvc := &corev1.Service{}\n\tif err := r.Client.Get(ctx, types.NamespacedName{Namespace: backendNs, Name: backendName}, backendSvc); err != nil {\n\t\tif k8serrors.IsNotFound(err) {\n\t\t\tscopedLog.DebugContext(ctx, \"Backend Service not found, clearing endpoints\",\n\t\t\t\tlogfields.Backend, backendRef)\n\t\t\treturn r.patchFrontend(ctx, frontend, nil, nil)\n\t\t}\n\t\treturn controllerruntime.Fail(fmt.Errorf(\"failed to get backend Service %s: %w\", backendRef, err))\n\t}\n\n\tmatchedPort := matchServicePort(backendSvc.Spec.Ports, uint16(servicePort), portProtocol(frontend.Ports))\n\tif matchedPort == nil {\n\t\tscopedLog.WarnContext(ctx, \"Backend Service does not expose requested port; clearing endpoints\",\n\t\t\tlogfields.Backend, backendRef,\n\t\t\tlogfields.Port, servicePort,","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/operator/pkg/gateway-api/endpointslice_reconcile.go#L81-L117","documentation":"In the EndpointSlice reconciler's Reconcile, a Service/Gateway frontend annotated with the Cilium backend-port annotation must carry a valid 16-bit unsigned port. strconv.ParseUint fails when the value is empty, non-numeric, or out of the uint16 range, producing 'invalid backend-port annotation %q: %w'. The reconcile is failed (controllerruntime.Fail), so the object is retried until the annotation is corrected.","triggerScenarios":"A frontend object carries the backend-port annotation with a value that ParseUint(…, 10, 16) rejects: empty string, \"https\", \"-1\", \"99999\" (>65535), or a value containing whitespace.","commonSituations":"Users hand-editing annotations and typing a service/protocol name instead of a port; automation templates leaving the annotation empty; copying a port value above 65535 from another system.","solutions":["Set the annotation to a plain numeric port in 1–65535, e.g. cilium.io/backend-port: \"8080\".","Remove the annotation entirely if it is not needed for the backend routing setup.","Fix any template/automation generating the annotation so it emits a validated integer.","Correct the annotation on the offending object to clear the stuck retry loop."],"exampleFix":"// before\nmetadata:\n  annotations:\n    cilium.io/backend-port: https\n// after\nmetadata:\n  annotations:\n    cilium.io/backend-port: \"443\"","handlingStrategy":"validation","validationCode":"v, ok := frontend.Annotations[gwModel.BackendPortAnnotation]\nif ok {\n\tif _, err := strconv.ParseUint(v, 10, 16); err != nil {\n\t\treturn fmt.Errorf(\"backend-port must be an integer in [1,65535], got %q\", v)\n\t}\n}","typeGuard":"func validBackendPort(v string) bool {\n\tp, err := strconv.ParseUint(v, 10, 16)\n\treturn err == nil && p > 0\n}","tryCatchPattern":"if _, err := strconv.ParseUint(frontend.Annotations[gwModel.BackendPortAnnotation], 10, 16); err != nil {\n\treturn controllerruntime.Fail(fmt.Errorf(\"invalid backend-port annotation %q: %w\",\n\t\tfrontend.Annotations[gwModel.BackendPortAnnotation], err))\n}\n// fix the annotation, then trigger a resync","preventionTips":["Validate annotation values with admission webhooks/OPA before persisting Services.","Always quote numeric ports in YAML annotations.","Use templates that emit integers, never service/protocol names, for the backend-port annotation."],"tags":["gateway-api","endpointslice","annotation","validation","kubernetes"],"backgroundTag":"invalid-annotation-value","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}