grpc/grpc-go · error

grpctransport: failed to create connection to server

Error message

grpctransport: failed to create connection to server %q: %v

What it means

Returned when the underlying gRPC client constructor fails to create a *grpc.ClientConn for the given ServerURI (grpc_transport.go:137). This wraps the raw error from grpc.NewClient (or a custom GRPCNewClient). Note this is a construction-time error, not a connection failure - gRPC dials lazily, so most network errors surface later on the stream.

Solutions

1. Validate the ServerURI format (scheme, authority, port) before Build.
2. If using a custom GRPCNewClient, test it in isolation against the same target.
3. Inspect the wrapped error - it names the underlying cause (e.g. 'no resolver registered for scheme').
4. Ensure the credentials bundle returned a non-nil TransportCredentials and that the gRPC version supports WithCredentialsBundle.

// Validate the target syntax before Build:
if si.ServerURI == "" || !looksLikeValidTarget(si.ServerURI) {
    return fmt.Errorf("invalid ServerURI %q", si.ServerURI)
}

tr, err := builder.Build(si)
if err != nil && strings.Contains(err.Error(), "failed to create connection to server") {
    // inspect wrapped error: invalid scheme, resolver missing, etc.
}

When it happens

Trigger: newClientFunc(si.ServerURI, dopts...) returns a non-nil error. With the default grpc.NewClient this typically means an invalid target syntax; with a custom GRPCNewClient it can be any error from that function.

Common situations: ServerURI uses a resolver scheme the build does not support (e.g. missing dns:/// prefix or an unknown scheme); a custom GRPCNewClient rejects the target; credentials bundle is incompatible with the dial options; gRPC version downgrade where NewClient signature differs.

Related errors

• extproc: failed to create channel to the external processor…
• failed to create a stream to external processor
• grpctransport: config
• grpctransport: Extensions field is %T, but must be %T in…
• grpctransport: Extensions is not set in ServerIdentifier

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/cf9a6a3e3a196e69. Report an issue: GitHub.

Appendix: source

Thrown at internal/xds/clients/grpctransport/grpc_transport.go:137

		return tr, nil
	}

	// Create a new gRPC client/channel for the server with the provided
	// credentials, server URI, and a byte codec to send and receive messages.
	// Also set a static keepalive configuration that is common across gRPC
	// language implementations.
	kpCfg := grpc.WithKeepaliveParams(keepalive.ClientParameters{
		Time:    5 * time.Minute,
		Timeout: 20 * time.Second,
	})
	dopts := []grpc.DialOption{kpCfg, grpc.WithCredentialsBundle(config.Credentials), grpc.WithDefaultCallOptions(grpc.ForceCodec(&byteCodec{}))}
	newClientFunc := grpc.NewClient
	if config.GRPCNewClient != nil {
		newClientFunc = config.GRPCNewClient
	}
	cc, err := newClientFunc(si.ServerURI, dopts...)
	if err != nil {
		return nil, fmt.Errorf("grpctransport: failed to create connection to server %q: %v", si.ServerURI, err)
	}
	tr := &grpcTransport{cc: cc}
	// Register a cleanup function that decrements the refs to the gRPC
	// transport each time Close() is called to close it and remove from
	// transports and connections map if last reference is being released.
	tr.cleanup = b.cleanupFunc(si, tr)

	// Add the newly created connection to the maps to re-use the transport
	// channel and track references.
	b.connections[si] = cc
	b.refs[si] = 1

	if logger.V(2) {
		logger.Infof("Created a new transport to the server for ServerIdentifier: %v", si)
	}
	return tr, nil
}

View on GitHub (pinned to 0c51461d27)