What causes "connection to %s terminated" in hyperledger/fabric?

Check the chaincode process logs for crashes or TLS handshake failures at startup

connection to %s terminated

Error message

connection to %s terminated

What it means

During chaincode launch, the peer attempts a chaincode-as-a-server connection via ConnectionHandler.Stream. If the stream terminates without successful registration, the launcher notifies the launch state with this error. It means the external chaincode process dropped or closed the connection before completing registration.

Source

Thrown at core/chaincode/runtime_launcher.go:95

		startFailCh = make(chan error, 1)
		timeoutCh = time.NewTimer(r.StartupTimeout).C

		go func() {
			// go through the build process to obtain connecion information
			ccservinfo, err := r.Runtime.Build(ccid)
			if err != nil {
				startFailCh <- errors.WithMessage(err, "error building chaincode")
				return
			}

			// chaincode server model indicated... proceed to connect to CC
			if ccservinfo != nil {
				if err = r.ConnectionHandler.Stream(ccid, ccservinfo, streamHandler); err != nil {
					startFailCh <- errors.WithMessagef(err, "connection to %s failed", ccid)
					return
				}

				launchState.Notify(errors.Errorf("connection to %s terminated", ccid))
				return
			}

			// default peer-as-server model... compute connection information for CC callback
			// and proceed to launch chaincode
			ccinfo, err := r.ChaincodeClientInfo(ccid)
			if err != nil {
				startFailCh <- errors.WithMessage(err, "could not get connection info")
				return
			}
			if ccinfo == nil {
				startFailCh <- errors.New("could not get connection info")
				return
			}
			if err = r.Runtime.Start(ccid, ccinfo); err != nil {
				startFailCh <- errors.WithMessage(err, "error starting container")
				return
			}

View on GitHub (pinned to 2736b63f8f)

Solutions

Check the chaincode process logs for crashes or TLS handshake failures at startup
Verify CORE_CHAINCODE_ID_NAME matches the chaincode name:version and the chaincode is listening on the configured address
Check mutual TLS configuration on both peer and chaincode (core.yaml chaincode.externalBuilders / tls settings)
Ensure network connectivity (Kubernetes service/pod DNS, firewall rules) between peer and chaincode container
Retry the transaction; if transient, the chaincode may restart and register successfully

Example fix

// before: chaincode container with no keep-alive / wrong port
// after: ensure chaincode serves on configured address
env: CORE_CHAINCODE_ID_NAME="mycc:1.0"
     CORE_CHAINCODE_ADDRESS="0.0.0.0:7052"
     CORE_CHAINCODE_TLS_ENABLED=true

Defensive patterns

Strategy: retry

Validate before calling

// pre-check external chaincode reachability
conn, err := net.DialTimeout("tcp", ccAddress, 5*time.Second)
if err != nil { return fmt.Errorf("chaincode %s not reachable at %s: %w", ccid, ccAddress, err) }
conn.Close()

Try / catch

err := launcher.Launch(ccid).
var transientErr *peer.ErrChaincodeTerminated
if errors.As(err, &transientErr) { /* retry launch after backoff */ }

Prevention

Use readiness probes so the peer only routes to healthy chaincode pods
Validate TLS certs before deployment on both peer and chaincode
Pin matching CORE_CHAINCODE_ID_NAME and address env vars
Monitor chaincode container restarts

When it happens

Trigger: ConnectionHandler.Stream returns nil but the connection closes before the chaincode registers; the external chaincode service at ccid's address terminates the stream mid-handshake.

Common situations: External chaincode (chaincode-as-a-service) crashing or being killed at startup; wrong TLS certificates/mutual TLS config; chaincode listening on wrong port or address; network/firewall dropping long-lived connections between peer and chaincode pod (common in Kubernetes).

Related errors

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