hyperledger/fabric · error

Error returned from build: %d "%s"

Error message

Error returned from build: %d "%s"

What it means

The builder container ran to completion but exited with a non-zero status code, meaning the build command (opts.Cmd) failed. DockerBuild logs the failing options at error level and returns the exit code together with the container's captured stdout/stderr output, which typically contains the compiler/toolchain error. This is the normal, expected failure path for a genuine compilation error in the chaincode source or its build command.

Source

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

	// -----------------------------------------------------------------------------------
	// 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)
	}
	defer resCont.Content.Close()
	io.Copy(opts.OutputStream, resCont.Content)

	return nil
}

// ParamsImage returns the go, os version and architecture of the ccenv image

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Read the quoted build output in the error message — it contains the actual compiler error from inside the container
2. Fix the chaincode source: resolve compile errors, ensure go.mod/go.sum are complete (go mod tidy) and dependencies are vendored or fetchable
3. Verify the build command (opts.Cmd) and any Env (GOPROXY, GONOSUMDB, GOFLAGS) match the toolchain in the builder image
4. Rebuild with a matching/current builder image (e.g. hyperledger/fabric-ccenv aligned with your Fabric version) if toolchain version mismatch is the cause

Example fix

// before: incomplete go.mod causing compile failure in builder
require github.com/hyperledger/fabric-contract-api-go
// after: generate complete module metadata before building
// run: go mod tidy && go mod vendor
require github.com/hyperledger/fabric-contract-api-go v1.2.2

// Validate chaincode package contents before invoking DockerBuild
if len(packageTarball) == 0 { return errors.New("empty chaincode package") }
// for Go: pre-check that source compiles locally
// cmd := exec.Command("go", "build", "./..."); run inside the package dir

if err := util.DockerBuild(opts, client); err != nil {
    var ec int
    if _, perr := fmt.Sscanf(err.Error(), "Error returned from build: %d", &ec); perr == nil {
        // surface the quoted build output to the user: real compiler error
        return fmt.Errorf("chaincode compile failed (exit %d): %w", ec, err)
    }
    return err
}

When it happens

Trigger: res.StatusCode > 0 after ContainerWait returns: the command wrapped as ['/bin/sh','-c',opts.Cmd] exits non-zero — compile errors in the chaincode source, missing dependencies, vendoring problems, unsupported toolchain flags, or a failing script inside the builder image.

Common situations: Chaincode Go code that does not compile (syntax or type errors); missing go.mod dependencies or private modules unreachable from the builder; GOFLAGS/GOCACHE issues inside the container; Node.js chaincode failing npm install; users upgrading Fabric where the ccenv toolchain version no longer matches the chaincode code.

Related errors

• Error executing build: %s "%s"
• platform builder failed
• Error waiting for container to complete: %s
• Error downloading output: %s
• docker image build failed

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