invalid label '%s'. Label must be non-empty, can only consis

Error message

invalid label '%s'. Label must be non-empty, can only consist of alphanumerics, symbols from '.+-_', and can only begin with alphanumerics

What it means

ValidateLabel rejects labels that don't match LabelRegexp ^[[:alnum:]][[:alnum:]_.+-]*$: the label must be non-empty, start with an alphanumeric, and contain only alphanumerics and . + - _ characters. It is called by ParseChaincodePackage/Parse and by Validate when a package or install request carries an invalid label.

Source

Thrown at core/chaincode/persistence/chaincode_package.go:253

// information (for instance the DB indexes) from a code package.
type MetadataProvider interface {
	GetDBArtifacts(codePackage []byte) ([]byte, error)
}

// ChaincodePackageParser provides the ability to parse chaincode packages.
type ChaincodePackageParser struct {
	MetadataProvider MetadataProvider
}

// LabelRegexp is the regular expression controlling the allowed characters
// for the package label.
var LabelRegexp = regexp.MustCompile(`^[[:alnum:]][[:alnum:]_.+-]*$`)

// ValidateLabel return an error if the provided label contains any invalid
// characters, as determined by LabelRegexp.
func ValidateLabel(label string) error {
	if !LabelRegexp.MatchString(label) {
		return errors.Errorf("invalid label '%s'. Label must be non-empty, can only consist of alphanumerics, symbols from '.+-_', and can only begin with alphanumerics", label)
	}

	return nil
}

// Parse parses a set of bytes as a chaincode package
// and returns the parsed package as a struct
func (ccpp ChaincodePackageParser) Parse(source []byte) (*ChaincodePackage, error) {
	ccPackageMetadata, codePackage, err := ParseChaincodePackage(source)
	if err != nil {
		return nil, err
	}

	dbArtifacts, err := ccpp.MetadataProvider.GetDBArtifacts(codePackage)
	if err != nil {
		return nil, errors.WithMessage(err, "error retrieving DB artifacts from code package")
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Change the label to start with a letter/digit and use only [A-Za-z0-9_.+-], e.g. mycc-v1.0.
Sanitize derived labels: replace ':' and '/' in image tags with '-' or '_' before packaging.
Quote shell variables and verify non-empty: label="${LABEL:?label required}".
Pre-validate with persistence.ValidateLabel before packaging in Go code.

Example fix

// before
label="myrepo/mycc:1.0"
// after
label="myrepo-mycc-1.0"

Defensive patterns

Strategy: validation

Validate before calling

var labelRe = regexp.MustCompile(`^[[:alnum:]][[:alnum:]_.+-]*$`)
func labelValid(s string) bool { return labelRe.MatchString(s) }
if !labelValid(label) {
	return fmt.Errorf("label %q invalid; use only alphanumerics and .+-_ and start alphanumerically", label)
}

Try / catch

if err := persistence.ValidateLabel(label); err != nil {
	return fmt.Errorf("fix --label (no spaces/:/ or / allowed): %w", err)
}

Prevention

Derive labels by replacing ':' and '/' in image tags with '-'.
Quote and default-check shell variables used as labels.
Call persistence.ValidateLabel early in tooling before packaging.
Keep labels short, e.g. name-version like mycc-1.0.

When it happens

Trigger: Calling ValidateLabel directly, installing/installing-and-approving a package whose --label contains spaces, colons, slashes, uppercase-forbidden symbols, non-ASCII characters, or is empty.

Common situations: Labels auto-built from image tags containing ':' or '/' (e.g. myrepo/mycc:1.0), labels with spaces from shell variables, or empty labels when the flag was omitted in scripts.

Related errors

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