hyperledger/fabric · error

channel members not initialized

Error message

channel members not initialized

What it means

Inside getStepClientStream, after a gRPC Step stream is opened, the manager re-reads ac.Chan2Members[channel] to find its own identity's stub. This error means the channel mapping vanished (or was never present) at stream-creation time even though the stub was being activated - typically because the manager was shut down or the channel mapping was concurrently rebuilt.

Source

Thrown at orderer/common/cluster/commauth.go:187

		probeConnection := func(conn *grpc.ClientConn) error {
			connState := conn.GetState()
			if connState == connectivity.Connecting {
				return errors.Errorf("connection to %d(%s) is in state %s", stub.ID, stub.Endpoint, connState)
			}
			return nil
		}

		clusterClient := orderer.NewClusterNodeServiceClient(conn)
		getStepClientStream := func(ctx context.Context) (StepClientStream, error) {
			stream, err := clusterClient.Step(ctx)
			if err != nil {
				return nil, err
			}

			membersMapping, exists := ac.Chan2Members[channel]
			if !exists {
				return nil, errors.Errorf("channel members not initialized")
			}
			nodeStub := membersMapping.LookupByIdentity(ac.NodeIdentity)
			if nodeStub == nil {
				return nil, errors.Errorf("node identity is missing in channel")
			}

			stepClientStream := &NodeClientStream{
				Version:           0,
				StepClient:        stream,
				SourceNodeID:      nodeStub.ID,
				DestinationNodeID: stub.ID,
				Signer:            ac.Signer,
				Channel:           channel,
			}
			return stepClientStream, nil
		}

		workerCountReporter := workerCountReporter{

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure Configure(channel, members) has been called for the channel on this exact AuthCommMgr instance before establishing streams.
2. Check whether Shutdown() was invoked - after shutdown, no new streams should be attempted; wait for restart and reconfigure.
3. Look for concurrent config updates removing/recreating the channel mapping; serialize Configure with stream creation (the manager lock already guards, so audit external map access).
4. If seen in tests/custom wiring, initialize Chan2Members via Configure rather than an empty map literal.

Example fix

// before
mgr := &cluster.AuthCommMgr{} // Chan2Members empty
stream, err := mgr.newStream(ctx, "mychannel")
// after
mgr.Configure("mychannel", members)
stream, err := mgr.newStream(ctx, "mychannel")

func membersInitialized(mgr *cluster.AuthCommMgr, channel string) bool {
    mgr.Lock.RLock()
    defer mgr.Lock.RUnlock()
    _, ok := mgr.Chan2Members[channel]
    return ok
}
if !membersInitialized(mgr, channel) {
    mgr.Configure(channel, members) // initialize before streaming
}

func channelMappingPresent(mgr *cluster.AuthCommMgr, channel string) bool {
    mgr.Lock.RLock()
    defer mgr.Lock.RUnlock()
    mapping, exists := mgr.Chan2Members[channel]
    return exists && mapping != nil
}

stream, err := getStream(ctx)
if err != nil {
    if strings.Contains(err.Error(), "channel members not initialized") {
        // membership mapping gone: likely shutdown or unconfigured channel; reconfigure and retry once
        comm.Configure(channel, members)
        stream, err = getStream(ctx)
    }
    return err
}

When it happens

Trigger: A Step stream is being created for a channel that is no longer (or not yet) in ac.Chan2Members: Shutdown() ran concurrently (Shutdown itself does not delete mappings, but a fresh AuthCommMgr with empty map was used), Configure was never called for this channel on this manager instance, or a config update replaced the mapping between Remote() and getStepClientStream execution.

Common situations: Orderer shutting down while streams are being created; channel removal/reconfiguration racing with stream creation; constructing AuthCommMgr with an empty Chan2Members and calling into stream paths without Configure; tests creating managers directly without populating membership.

Related errors

• request message is nil
• stream %d is stale
• OrdererOrg config does not allow sub-groups
• Attempted to set the batch size preferred max bytes (%v) gre
• Attempted to set the batch timeout to a invalid value: %s

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/80c09c607678c19e. Report an issue: GitHub.