cilium/cilium · error

start transport: %w

Error message

start transport: %w

What it means

The XDSClient's process goroutine wraps any failure from establishing the xDS gRPC transport stream (trans := c.xds.transport(...)) with the prefix 'start transport:'. It means the AggregatedDiscoveryService stream could not be opened, so the client cannot talk to the xDS management server at all and Run returns. The underlying cause (connection refused, TLS failure, RPC error) is preserved via %w.

Source

Thrown at pkg/xds/experimental/client/client.go:208

		}
	}
}

// process creates a transport, sends initial requests and spins up two additional goroutines:
//   - fetchResponses which passes objects from Recv calls onto a queue
//   - loop which processes responses queued up by fetchResponses goroutine, and
//     processes requests queued up by calls to Observe method
//
// If any of the goroutines fails with non-retryable error, or terminates, it
// will stop the transport (by cancelling its context) and wait for all
// goroutines started by it to finish processing.
func (c *XDSClient[ReqT, RespT]) process(parentCtx context.Context, client discoverypb.AggregatedDiscoveryServiceClient) error {
	ctx, cancel := context.WithCancel(parentCtx)

	trans, err := c.xds.transport(ctx, client)
	if err != nil {
		cancel()
		return fmt.Errorf("start transport: %w", err)
	}

	errRespCh := make(chan error, 1)
	go c.fetchResponses(ctx, errRespCh, trans)
	errLoopCh := make(chan error, 1)
	go c.loop(ctx, errLoopCh, trans)

	defer func() {
		cancel()
		<-errLoopCh
		<-errRespCh
	}()

	for {
		select {
		case <-ctx.Done():
			return ctx.Err()
		case err, ok := <-errRespCh:

View on GitHub (pinned to ac7b90affa)

Solutions

1. Verify the xDS server address/port configuration the client was built with is reachable (nc/curl the host:port).
2. Check mTLS/TLS credentials: ensure the CA cert, client cert and key files exist and are valid and match the server's expectations.
3. Check connectivity from the agent pod/host to the xDS server (network policies, firewall, service endpoints).
4. Inspect the wrapped error returned to Run; it identifies the concrete transport failure to fix.
5. If intentional shutdown, this error is expected when the parent context is canceled; treat context.Canceled as benign.

Example fix

// before
cfg := xdsclient.Config{ TypeURLs: ..., } // server address left default/empty
cl, _ := xdsclient.NewClient(cfg)
go cl.Run(ctx)
// after
cfg := xdsclient.Config{ TypeURLs: ... }
// ensure address matches the running xDS server, e.g.
// grpc.WithContextDialer to 'xds-server:18000' + valid transport credentials
cl, err := xdsclient.NewClient(cfg)
if err != nil { log.Fatal(err) }
go cl.Run(ctx)

// before Run: verify reachability of the xDS endpoint
host, port := "xds-server", 18000
if conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), 2*time.Second); err != nil {
	return fmt.Errorf("xDS server %s:%d unreachable: %w", host, port, err)
} else { conn.Close() }

err := cl.Run(ctx)
if err != nil && strings.HasPrefix(err.Error(), "start transport:") {
	log.Errorf("xDS transport failed to start: %v", errors.Unwrap(err))
	// retry with backoff unless ctx canceled
	if !errors.Is(err, context.Canceled) { scheduleRestart() }
}

When it happens

Trigger: XDSClient.Run is called and c.xds.transport() fails to create the gRPC bidi stream — e.g. the gRPC channel to the xDS server is in TRANSIENT_FAILURE, the transport builder's initial stream creation returns an error, or the parent context is already canceled before the stream opens.

Common situations: xDS server address/port misconfigured (cilium-configmap or --xds flags pointing to wrong host), the xDS management server (or an intermediate proxy) is down, mTLS certificates are missing/expired so the TLS handshake fails, or network policy/firewall blocks the gRPC port.

Related errors

• recv: %w
• nodeId is empty
• type URL is required for ADS
• mismatching type URL
• unknown type URL

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