What causes "failed to wait on container exit" in hyperledger/fabric?

Verify Docker is running and the peer's docker socket access works (docker ps from the peer's environment)

failed to wait on container exit

Error message

failed to wait on container exit

What it means

After the container was started, r.Runtime.Wait(ccid) failed, so the launcher cannot determine the container's exit code. The container runtime (Docker) call itself errored, which is wrapped and reported as the launch result.

Source

Thrown at core/chaincode/runtime_launcher.go:116

			// 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
			}
			exitCode, err := r.Runtime.Wait(ccid)
			if err != nil {
				launchState.Notify(errors.Wrap(err, "failed to wait on container exit"))
			}
			launchState.Notify(errors.Errorf("container exited with %d", exitCode))
		}()
	}

	var err error
	select {
	case <-launchState.Done():
		err = errors.WithMessage(launchState.Err(), "chaincode registration failed")
	case err = <-startFailCh:
		launchState.Notify(err)
		r.Metrics.LaunchFailures.With("chaincode", ccid).Add(1)
	case <-timeoutCh:
		err = errors.Errorf("timeout expired while starting chaincode %s for transaction", ccid)
		launchState.Notify(err)
		r.Metrics.LaunchTimeouts.With("chaincode", ccid).Add(1)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Verify Docker is running and the peer's docker socket access works (docker ps from the peer's environment)
Restart the peer to re-establish the Docker client connection
Check for container garbage-collection/cleanup jobs removing containers mid-run
Inspect peer logs for the wrapped underlying Docker error to pinpoint the runtime failure

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure Docker is reachable from the peer host before launch
exec.Command("docker", "info").Run() // must succeed

Try / catch

if err := launcher.Launch(ccid); err != nil && strings.Contains(err.Error(), "failed to wait on container exit") {
    // check Docker daemon health, then retry Launch
}

Prevention

Monitor Docker daemon health on peer hosts
Avoid external jobs deleting containers while the peer runs
Grant the peer's docker socket mount correct permissions
Pin a compatible Docker version for your Fabric release

When it happens

Trigger: Runtime.Wait returns an error while the launcher goroutine blocks on container exit — e.g., Docker daemon unavailable or the container record disappeared.

Common situations: Docker daemon restarted or unreachable mid-launch; container removed by an external cleaner while the peer waited; docker socket permission issues on the peer host.

Related errors

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