xds: Propagate status cause through XdsDepManager

Often there is no cause, but connect(), channel credentials, and call
credentials failures on the control plane RPC can include a useful
causal exception.

This was triggered by seeing an error like below, but it didn't include
the cause, which would have included HTTP error information from the
failure fetching the credential.
```
UNAVAILABLE: Error retrieving LDS resource xdstp://traffic-director-c2p.xds.googleapis.com/envoy.config.listener.v3.Listener/bigtable.googleapis.com: UNAUTHENTICATED: Failed computing credential metadata nodeID: C2P-798500073
```

Author: ejona86

api/src/testFixtures/java/io/grpc/StatusMatcher.java

@@ -26,7 +26,7 @@
  */
 public final class StatusMatcher implements ArgumentMatcher<Status> {
   public static StatusMatcher statusHasCode(ArgumentMatcher<Status.Code> codeMatcher) {
-    return new StatusMatcher(codeMatcher, null);
+    return new StatusMatcher(codeMatcher, null, null);
   }
 
   public static StatusMatcher statusHasCode(Status.Code code) {
@@ -35,17 +35,20 @@ public static StatusMatcher statusHasCode(Status.Code code) {
 
   private final ArgumentMatcher<Status.Code> codeMatcher;
   private final ArgumentMatcher<String> descriptionMatcher;
+  private final ArgumentMatcher<Throwable> causeMatcher;
 
   private StatusMatcher(
       ArgumentMatcher<Status.Code> codeMatcher,
-      ArgumentMatcher<String> descriptionMatcher) {
+      ArgumentMatcher<String> descriptionMatcher,
+      ArgumentMatcher<Throwable> causeMatcher) {
     this.codeMatcher = checkNotNull(codeMatcher, "codeMatcher");
     this.descriptionMatcher = descriptionMatcher;
+    this.causeMatcher = causeMatcher;
   }
 
   public StatusMatcher andDescription(ArgumentMatcher<String> descriptionMatcher) {
     checkState(this.descriptionMatcher == null, "Already has a description matcher");
-    return new StatusMatcher(codeMatcher, descriptionMatcher);
+    return new StatusMatcher(codeMatcher, descriptionMatcher, causeMatcher);
   }
 
   public StatusMatcher andDescription(String description) {
@@ -56,11 +59,21 @@ public StatusMatcher andDescriptionContains(String substring) {
     return andDescription(new StringContainsMatcher(substring));
   }
 
+  public StatusMatcher andCause(ArgumentMatcher<Throwable> causeMatcher) {
+    checkState(this.causeMatcher == null, "Already has a cause matcher");
+    return new StatusMatcher(codeMatcher, descriptionMatcher, causeMatcher);
+  }
+
+  public StatusMatcher andCause(Throwable cause) {
+    return andCause(new EqualsMatcher<>(cause));
+  }
+
   @Override
   public boolean matches(Status status) {
     return status != null
         && codeMatcher.matches(status.getCode())
-        && (descriptionMatcher == null || descriptionMatcher.matches(status.getDescription()));
+        && (descriptionMatcher == null || descriptionMatcher.matches(status.getDescription()))
+        && (causeMatcher == null || causeMatcher.matches(status.getCause()));
   }
 
   @Override
@@ -72,6 +85,10 @@ public String toString() {
       sb.append(", description=");
       sb.append(descriptionMatcher);
     }
+    if (causeMatcher != null) {
+      sb.append(", cause=");
+      sb.append(causeMatcher);
+    }
     sb.append("}");
     return sb.toString();
   }

xds/src/main/java/io/grpc/xds/XdsDependencyManager.java

@@ -30,6 +30,7 @@
 import io.grpc.Status;
 import io.grpc.StatusOr;
 import io.grpc.SynchronizationContext;
+import io.grpc.internal.GrpcUtil;
 import io.grpc.internal.RetryingNameResolver;
 import io.grpc.xds.Endpoints.LocalityLbEndpoints;
 import io.grpc.xds.VirtualHost.Route.RouteAction.ClusterWeight;
@@ -652,13 +653,10 @@ public void onResourceChanged(StatusOr<T> update) {
         data = update;
         subscribeToChildren(update.getValue());
       } else {
-        Status status = update.getStatus();
-        Status translatedStatus = Status.UNAVAILABLE.withDescription(
-            String.format("Error retrieving %s: %s. Details: %s%s",
-                toContextString(),
-                status.getCode(),
-                status.getDescription() != null ? status.getDescription() : "",
-                nodeInfo()));
+        Status translatedStatus = GrpcUtil.statusWithDetails(
+            Status.Code.UNAVAILABLE,
+            "Error retrieving " + toContextString() + nodeInfo(),
+            update.getStatus());
 
         data = StatusOr.fromStatus(translatedStatus);
       }

xds/src/test/java/io/grpc/xds/CdsLoadBalancer2Test.java

@@ -255,9 +255,9 @@ public void nonAggregateCluster_resourceNotExist_returnErrorPicker() {
     startXdsDepManager();
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
-    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + ": NOT_FOUND. "
-        + "Details: Timed out waiting for resource " + CLUSTER
-        + " from xDS server nodeID: " + NODE_ID;
+    String expectedDescription = "Error retrieving CDS resource " + CLUSTER
+        + " nodeID: " + NODE_ID
+        + ": NOT_FOUND: Timed out waiting for resource " + CLUSTER + " from xDS server";
     Status unavailable = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPickerStatus(pickerCaptor.getValue(), unavailable);
     assertThat(childBalancers).isEmpty();
@@ -311,8 +311,9 @@ public void nonAggregateCluster_resourceRevoked() {
     controlPlaneService.setXdsConfig(ADS_TYPE_URL_CDS, ImmutableMap.of());
 
     assertThat(childBalancer.shutdown).isTrue();
-    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + ": NOT_FOUND. "
-        + "Details: Resource " + CLUSTER + " does not exist nodeID: " + NODE_ID;
+    String expectedDescription = "Error retrieving CDS resource " + CLUSTER
+        + " nodeID: " + NODE_ID
+        + ": NOT_FOUND: Resource " + CLUSTER + " does not exist";
     Status unavailable = Status.UNAVAILABLE.withDescription(expectedDescription);
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
@@ -515,9 +516,9 @@ public void aggregateCluster_noNonAggregateClusterExits_returnErrorPicker() {
 
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
-    String expectedDescription = "Error retrieving CDS resource " + cluster1 + ": NOT_FOUND. "
-        + "Details: Timed out waiting for resource " + cluster1 + " from xDS server nodeID: "
-        + NODE_ID;
+    String expectedDescription = "Error retrieving CDS resource " + cluster1
+        + " nodeID: " + NODE_ID
+        + ": NOT_FOUND: Timed out waiting for resource " + cluster1 + " from xDS server";
     Status status = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPickerStatus(pickerCaptor.getValue(), status);
     assertThat(childBalancers).isEmpty();

xds/src/test/java/io/grpc/xds/ClusterResolverLoadBalancerTest.java

@@ -697,8 +697,8 @@ public void onlyEdsClusters_resourceNeverExist_returnErrorPicker() {
 
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
-    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + ": NOT_FOUND. "
-        + "Details: Timed out waiting for resource " + CLUSTER + " from xDS server nodeID: node-id";
+    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + " nodeID: node-id: "
+        + "NOT_FOUND: Timed out waiting for resource " + CLUSTER + " from xDS server";
     Status expectedError = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPicker(pickerCaptor.getValue(), expectedError, null);
   }
@@ -720,8 +720,8 @@ public void cdsMissing_handledDirectly() {
     assertThat(childBalancers).hasSize(0);  // no child LB policy created
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
-    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + ": NOT_FOUND. "
-        + "Details: Timed out waiting for resource " + CLUSTER + " from xDS server nodeID: node-id";
+    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + " nodeID: node-id: "
+        + "NOT_FOUND: Timed out waiting for resource " + CLUSTER + " from xDS server";
     Status expectedError = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPicker(pickerCaptor.getValue(), expectedError, null);
     assertPicker(pickerCaptor.getValue(), expectedError, null);
@@ -751,8 +751,8 @@ public void cdsRevoked_handledDirectly() {
     controlPlaneService.setXdsConfig(ADS_TYPE_URL_CDS, ImmutableMap.of());
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
-    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + ": NOT_FOUND. "
-        + "Details: Resource " + CLUSTER + " does not exist nodeID: node-id";
+    String expectedDescription = "Error retrieving CDS resource " + CLUSTER + " nodeID: node-id: "
+        + "NOT_FOUND: Resource " + CLUSTER + " does not exist";
     Status expectedError = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPicker(pickerCaptor.getValue(), expectedError, null);
     assertThat(childBalancer.shutdown).isTrue();
@@ -767,8 +767,8 @@ public void edsMissing_failsRpcs() {
     verify(helper).updateBalancingState(
         eq(ConnectivityState.TRANSIENT_FAILURE), pickerCaptor.capture());
     String expectedDescription = "Error retrieving EDS resource " + EDS_SERVICE_NAME
-        + ": NOT_FOUND. Details: Timed out waiting for resource " + EDS_SERVICE_NAME
-        + " from xDS server nodeID: node-id";
+        + " nodeID: node-id: "
+        + "NOT_FOUND: Timed out waiting for resource " + EDS_SERVICE_NAME + " from xDS server";
     Status expectedError = Status.UNAVAILABLE.withDescription(expectedDescription);
     assertPicker(pickerCaptor.getValue(), expectedError, null);
   }

xds/src/test/java/io/grpc/xds/FailingClientInterceptor.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc.xds;
+
+import static java.util.Objects.requireNonNull;
+
+import io.grpc.CallOptions;
+import io.grpc.Channel;
+import io.grpc.ClientCall;
+import io.grpc.ClientInterceptor;
+import io.grpc.Metadata;
+import io.grpc.MethodDescriptor;
+import io.grpc.NoopClientCall;
+import io.grpc.Status;
+
+/**
+ * An interceptor that fails all RPCs with the provided status.
+ */
+final class FailingClientInterceptor implements ClientInterceptor {
+  private final Status status;
+
+  public FailingClientInterceptor(Status status) {
+    this.status = requireNonNull(status, "status");
+  }
+
+  @Override
+  public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
+      MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
+    return new NoopClientCall<ReqT, RespT>() {
+      @Override
+      public void start(Listener<RespT> responseListener, Metadata headers) {
+        responseListener.onClose(status, new Metadata());
+      }
+    };
+  }
+}

xds/src/test/java/io/grpc/xds/XdsDependencyManagerTest.java

@@ -409,6 +409,32 @@ public void testTcpListenerErrors() {
     testWatcher.verifyStats(0, 1);
   }
 
+  @Test
+  public void testControlPlaneError() {
+    Status forcedStatus = Status.NOT_FOUND
+        .withDescription("expected")
+        .withCause(new IllegalArgumentException("a random exception"));
+    xdsClient.shutdown();
+    xdsClient = XdsTestUtils.createXdsClient(
+      Collections.singletonList("control-plane"),
+      serverInfo -> new GrpcXdsTransportFactory.GrpcXdsTransport(
+          InProcessChannelBuilder.forName(serverInfo.target())
+            .directExecutor()
+            .intercept(new FailingClientInterceptor(forcedStatus))
+            .build()),
+      fakeClock);
+    xdsDependencyManager = new XdsDependencyManager(
+        xdsClient, syncContext, serverName, serverName, nameResolverArgs);
+    xdsDependencyManager.start(xdsConfigWatcher);
+
+    verify(xdsConfigWatcher).onUpdate(
+        argThat(StatusOrMatcher.hasStatus(
+            statusHasCode(Status.Code.UNAVAILABLE)
+              .andDescriptionContains(forcedStatus.getDescription())
+              .andCause(forcedStatus.getCause()))));
+    testWatcher.verifyStats(0, 1);
+  }
+
   @Test
   public void testMissingRds() {
     String rdsName = "badRdsName";