hyperledger/fabric · error

failed to create new stream

Error message

failed to create new stream

What it means

NewStream in remotecontext.go wraps any error returned by stream.Auth() with "failed to create new stream". Authentication of the newly created gRPC stream to a remote cluster member failed, so the stream is not registered and cannot be used for Step/Deliver traffic.

Source

Thrown at orderer/common/cluster/remotecontext.go:118

	}

	s.expCheck = &certificateExpirationCheck{
		minimumExpirationWarningInterval: rc.minimumExpirationWarningInterval,
		expirationWarningThreshold:       rc.certExpWarningThreshold,
		endpoint:                         s.Endpoint,
		nodeName:                         s.NodeName,
		alert: func(template string, args ...any) {
			s.Logger.Warningf(template, args...)
		},
	}

	if cert := util.ExtractCertificateFromContext(stream.Context()); cert != nil {
		s.expCheck.expiresAt = cert.NotAfter
	}

	err = stream.Auth()
	if err != nil {
		return nil, errors.Wrap(err, "failed to create new stream")
	}

	rc.Logger.Debugf("Created new stream to %s with ID of %d and buffer size of %d",
		rc.endpoint, streamID, cap(s.sendBuff))

	rc.streamsByID.Store(streamID, s)
	rc.Metrics.reportEgressStreamCount(rc.Channel, atomic.LoadUint32(&rc.streamsByID.size))

	go func() {
		rc.workerCountReporter.increment(s.metrics)
		s.serviceStream()
		rc.workerCountReporter.decrement(s.metrics)
	}()

	return s, nil
}

// Abort aborts the contexts the RemoteContext uses, thus effectively

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Compare the local node's TLS CA cert with General.Cluster.TLS root CAs on the peer side and re-sync certificates
2. Check certificate expiry dates and renew/rotate TLS certs on the ordering nodes
3. Verify General.TLS and General.Cluster.TLS settings (enabled, clientAuthRequired, root CAs) are consistent across all nodes
4. Inspect remote node logs for the underlying auth rejection reason

Example fix

// before (misconfig example)
General:
  TLS:
    Enabled: true
  Cluster:
    TLS:
      RootCAs: [old-ca.pem]
// after
General:
  TLS:
    Enabled: true
  Cluster:
    TLS:
      RootCAs: [current-ca.pem]

cert, err := tls.LoadX509KeyPair(tlsCert, tlsKey)
if err != nil { return fmt.Errorf("local TLS material unusable: %w", err) }
if time.Now().After(cert.Leaf.NotAfter) { return errors.New("TLS certificate expired") }

rc := cluster.NewRemoteContext(...)
s, err := rc.NewStream(endpoint)
if err != nil && strings.Contains(err.Error(), "failed to create new stream") {
    // re-auth: refresh CAs / certificates, then retry stream creation
    return err
}

When it happens

Trigger: stream.Auth() fails because the remote node's identity (certificate) is not signed by the expected CA; certificate expiry; TLS handshake succeeded but mutual auth/certificate extraction failed during cluster RPC authentication.

Common situations: Expired or rotated TLS certificates not yet trusted by both sides; mismatched TLSRootCAs in General.Cluster config; a node rejoining the cluster after cert rotation before the others got the new CA; wrong TLS handshake timeout (stream still authenticating when deadline hit).

Related errors

• invalid request object
• session binding read failed
• session binding mismatch
• TLSBinding failed
• access denied, client identity wasn't supplied

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