Error constructing Docker VM Name. '%s' breaks Docker's repo

Error message

Error constructing Docker VM Name. '%s' breaks Docker's repository naming rules

What it means

GetVMNameForDocker sanitizes the chaincode VM name (replacing invalid characters with '-'), lowercases it, appends a hash, then validates the result against Docker's image repository name regex. If the composed image name still violates Docker's repository naming rules, this error is returned and no image name is produced. The log message prints the original name while the error prints the sanitized imageName.

Source

Thrown at core/container/dockercontroller/dockercontroller.go:448

// GetVMNameForDocker formats the docker image from peer information. This is
// needed to keep image (repository) names unique in a single host, multi-peer
// environment (such as a development environment). It computes the hash for the
// supplied image name and then appends it to the lowercase image name to ensure
// uniqueness.
func (vm *DockerVM) GetVMNameForDocker(ccid string) (string, error) {
	name := vm.preFormatImageName(ccid)
	// pre-2.0 used "-" as the separator in the ccid, so replace ":" with
	// "-" here to ensure 2.0 peers can find pre-2.0 cc images
	name = strings.ReplaceAll(name, ":", "-")
	hash := hex.EncodeToString(util.ComputeSHA256([]byte(name)))
	saniName := vmRegExp.ReplaceAllString(name, "-")
	imageName := strings.ToLower(fmt.Sprintf("%s-%s", saniName, hash))

	// Check that name complies with Docker's repository naming rules
	if !imageRegExp.MatchString(imageName) {
		dockerLogger.Errorf("Error constructing Docker VM Name. '%s' breaks Docker's repository naming rules", name)
		return "", fmt.Errorf("Error constructing Docker VM Name. '%s' breaks Docker's repository naming rules", imageName)
	}

	return imageName, nil
}

func (vm *DockerVM) preFormatImageName(ccid string) string {
	name := ccid

	if vm.NetworkID != "" && vm.PeerID != "" {
		name = fmt.Sprintf("%s-%s-%s", vm.NetworkID, vm.PeerID, name)
	} else if vm.NetworkID != "" {
		name = fmt.Sprintf("%s-%s", vm.NetworkID, name)
	} else if vm.PeerID != "" {
		name = fmt.Sprintf("%s-%s", vm.PeerID, name)
	}

	return name
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Shorten or rename the chaincode label/package ID so the sanitized name is a valid Docker repo name (alphanumeric, separated by ., _, -, no leading/trailing separators).
Check the imageName printed in the error for illegal characters like leading '-' or '.' introduced by sanitization, and adjust the source name accordingly.
Upgrade Fabric if using an older version - name sanitization rules have been improved over releases.

Example fix

// before
name := "-my_chaincode!!" // sanitizes to "--my_chaincode--", invalid repo name
// after
name := "my_chaincode"

Defensive patterns

Strategy: validation

Validate before calling

// Go: pre-validate a chaincode name against docker repo rules
import "regexp"
var imageRegExp = regexp.MustCompile(`^[a-z0-9]+((\.|_|__|-+)[a-z0-9]+)*$`)
func validDockerName(name string) bool { return len(name) <= 128 && imageRegExp.MatchString(name) }

Try / catch

imageName, err := vm.GetVMNameForDocker(name)
if err != nil {
    if strings.Contains(err.Error(), "breaks Docker's repository naming rules") {
        // sanitize/shorten the label before retrying
    }
}

Prevention

Use lowercase alphanumeric chaincode/package labels with . _ or - separators only.
Keep names short (<100 chars) leaving room for the appended hash.
Avoid names whose sanitized form starts/ends with '-', '.', or '_' (e.g. names of pure symbols).
Test name sanitization in CI before deploying chaincode with unusual labels.

When it happens

Trigger: GetVMNameForDocker(name) (called by Build, buildImage, Start) when the saniName+hash result fails imageRegExp.MatchString - e.g. name starting or ending with '-'/'.' after sanitization, empty name, or a name longer than 128 chars.

Common situations: Chaincode labels or package IDs containing unusual characters that sanitize to leading/trailing separators; extremely long chaincode names; names composed only of characters replaced by '-'.

Related errors

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