From b864cf0c523ab9ab80da9b2742b7b36d914aa3ee Mon Sep 17 00:00:00 2001
From: Mike Ng <ming@redhat.com>
Date: Tue, 11 Aug 2026 03:50:53 -0400
Subject: [PATCH] Improve diagnostic message when hosted addon lease is not
 found (#1651)

Signed-off-by: Mike Ng <ming@redhat.com>
---
 .../spoke/addon/lease_controller.go           |  9 ++++-
 .../spoke/addon/lease_controller_test.go      | 40 +++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/pkg/registration/spoke/addon/lease_controller.go b/pkg/registration/spoke/addon/lease_controller.go
index 5056e54b1..e8d323e3a 100644
--- a/pkg/registration/spoke/addon/lease_controller.go
+++ b/pkg/registration/spoke/addon/lease_controller.go
@@ -125,11 +125,18 @@ func (c *managedClusterAddOnLeaseController) syncSingle(ctx context.Context,
 	var condition metav1.Condition
 	switch {
 	case errors.IsNotFound(err):
+		message := fmt.Sprintf("The status of %s add-on is unknown.", addOn.Name)
+		if isAddonRunningOutsideManagedCluster(addOn) {
+			// No lease on the declared hosting cluster usually means it doesn't match the klusterlet's actual hosting cluster.
+			hostingCluster := addOn.Annotations[addonv1beta1.HostingClusterNameAnnotationKey]
+			message = fmt.Sprintf("%s No lease found on hosting cluster %q; verify it matches the cluster "+
+				"where this managed cluster's klusterlet actually runs.", message, hostingCluster)
+		}
 		condition = metav1.Condition{
 			Type:    addonv1beta1.ManagedClusterAddOnConditionAvailable,
 			Status:  metav1.ConditionUnknown,
 			Reason:  "ManagedClusterAddOnLeaseNotFound",
-			Message: fmt.Sprintf("The status of %s add-on is unknown.", addOn.Name),
+			Message: message,
 		}
 	case err != nil:
 		return err
diff --git a/pkg/registration/spoke/addon/lease_controller_test.go b/pkg/registration/spoke/addon/lease_controller_test.go
index 008750cb4..89ac530dc 100644
--- a/pkg/registration/spoke/addon/lease_controller_test.go
+++ b/pkg/registration/spoke/addon/lease_controller_test.go
@@ -3,6 +3,7 @@ package addon
 import (
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 
@@ -332,6 +333,45 @@ func TestSync(t *testing.T) {
 				}
 			},
 		},
+		{
+			name:     "no addon lease on management cluster names the hosting cluster in the message",
+			queueKey: "test/test",
+			addOns: []runtime.Object{&addonv1beta1.ManagedClusterAddOn{
+				ObjectMeta: metav1.ObjectMeta{
+					Namespace: testinghelpers.TestManagedClusterName,
+					Name:      "test",
+					Annotations: map[string]string{
+						addonv1beta1.HostingClusterNameAnnotationKey: "cluster1",
+					},
+				},
+				Spec: addonv1beta1.ManagedClusterAddOnSpec{},
+				Status: addonv1beta1.ManagedClusterAddOnStatus{
+					Namespace: "test",
+				},
+			}},
+			hubLeases:        []runtime.Object{},
+			managementLeases: []runtime.Object{},
+			validateActions: func(t *testing.T, ctx *testingcommon.FakeSyncContext, actions []clienttesting.Action) {
+				testingcommon.AssertActions(t, actions, "patch")
+				patch := actions[0].(clienttesting.PatchAction).GetPatch()
+				addOn := &addonv1beta1.ManagedClusterAddOn{}
+				err := json.Unmarshal(patch, addOn)
+				if err != nil {
+					t.Fatal(err)
+				}
+				addOnCond := meta.FindStatusCondition(addOn.Status.Conditions, "Available")
+				if addOnCond == nil {
+					t.Errorf("expected addon available condition, but failed")
+					return
+				}
+				if addOnCond.Status != metav1.ConditionUnknown {
+					t.Errorf("expected addon available condition is unknown, but failed")
+				}
+				if !strings.Contains(addOnCond.Message, "cluster1") {
+					t.Errorf("expected message to name the declared hosting cluster, got: %s", addOnCond.Message)
+				}
+			},
+		},
 		{
 			name:     "addon has customized health check",
 			queueKey: "test/test",