What causes "Error waiting for container to complete: %s" in hyperledger/fabric?

Check docker daemon logs and uptime (docker info, journalctl -u docker) for a restart or crash during the build window

Error waiting for container to complete: %s

Error message

Error waiting for container to complete: %s

What it means

After ContainerStart succeeds, DockerBuild blocks on client.ContainerWait. If the wait call's error channel delivers an error (docker API/stream failure while waiting for the container to exit) instead of a WaitResponse, the attached container stream is closed and this error is returned. It means the build outcome is unknown because the daemon-side wait itself failed, not that compilation failed.

Source

Thrown at core/chaincode/platforms/util/utils.go:150

	// Launch the actual build, realizing the Env/Cmd specified at container creation
	// -----------------------------------------------------------------------------------
	_, err = client.ContainerStart(context.Background(), container.ID, dcli.ContainerStartOptions{})
	if err != nil {
		buff, _ := io.ReadAll(cw.Reader)
		cw.Close()
		return fmt.Errorf("Error executing build: %s \"%s\"", err, string(buff))
	}

	// -----------------------------------------------------------------------------------
	// Wait for the build to complete and gather the return value
	// -----------------------------------------------------------------------------------
	resWait := client.ContainerWait(context.Background(), container.ID, dcli.ContainerWaitOptions{})
	var res dcontainer.WaitResponse
	select {
	case res = <-resWait.Result:
	case err = <-resWait.Error:
		cw.Close()
		return fmt.Errorf("Error waiting for container to complete: %s", err)
	}

	// Wait for stream copying to complete before accessing stdout.
	defer cw.Close()
	buff, _ := io.ReadAll(cw.Reader)
	if res.StatusCode > 0 {
		logger.Errorf("Docker build failed using options: %s", opts)
		return fmt.Errorf("Error returned from build: %d \"%s\"", res.StatusCode, string(buff))
	}

	logger.Debugf("Build output is %s", string(buff))

	// -----------------------------------------------------------------------------------
	// Finally, download the result
	// -----------------------------------------------------------------------------------
	resCont, err := client.CopyFromContainer(context.Background(), container.ID, dcli.CopyFromContainerOptions{SourcePath: "/chaincode/output/."})
	if err != nil {
		return fmt.Errorf("Error downloading output: %s", err)

View on GitHub (pinned to 2736b63f8f)

Solutions

Check docker daemon logs and uptime (docker info, journalctl -u docker) for a restart or crash during the build window
Ensure nothing else removes containers concurrently (cleanup scripts, orchestrators, docker system prune with --force)
Retry the chaincode build; transient daemon/connection failures usually succeed on a second attempt
If using a remote DOCKER_HOST, verify the connection is stable and increase daemon/API timeouts

Defensive patterns

Strategy: retry

Validate before calling

// Pre-check daemon connectivity before starting a build
if _, err := client.Ping(context.Background()); err != nil {
    return fmt.Errorf("docker daemon unreachable: %w", err)
}

Try / catch

const maxAttempts = 3
for i := 1; i <= maxAttempts; i++ {
    err := util.DockerBuild(opts, client)
    if err == nil { break }
    if strings.Contains(err.Error(), "Error waiting for container to complete") && i < maxAttempts {
        time.Sleep(time.Duration(i) * time.Second)
        continue
    }
    return err
}

Prevention

Never run docker rm -f / prune scripts that could touch peer-managed builder containers
Ensure the docker daemon is stable (watch for restarts during long builds)
Use a local docker socket rather than an unreliable remote DOCKER_HOST
Bound build durations so containers are not left waiting indefinitely

When it happens

Trigger: The ContainerWait result channel's Error channel receives a value: the docker daemon connection dropped while waiting, the container was forcibly removed by another process during the wait, or the daemon returned an API error on the wait endpoint.

Common situations: Docker daemon restart or crash during a long chaincode compilation; an external 'docker rm -f' (e.g. a cleanup script or timeout killer) removing the ephemeral builder container mid-build; network interruption between the peer and a remote docker endpoint (DOCKER_HOST) during the wait.

Related errors

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