invalid chaincode name '%s'. Names can only consist of alpha

Error message

invalid chaincode name '%s'. Names can only consist of alphanumerics, '_', and '-' and can only begin with alphanumerics

What it means

validateInput enforces ChaincodeNameRegExp on the chaincode name supplied to ApproveChaincodeDefinitionForMyOrg or CommitChaincodeDefinition. Names may only contain alphanumerics, underscore, and dash, and must start with a letter or digit. Anything else is rejected.

Source

Thrown at core/chaincode/lifecycle/scc.go:727

	ChaincodeNameRegExp    = regexp.MustCompile("^[a-zA-Z0-9]+([-_][a-zA-Z0-9]+)*$")
	ChaincodeVersionRegExp = regexp.MustCompile("^[A-Za-z0-9_.+-]+$")

	collectionNameRegExp = regexp.MustCompile("^[A-Za-z0-9-]+([A-Za-z0-9_-]+)*$")

	// currently defined system chaincode names that shouldn't
	// be allowed as user-defined chaincode names
	systemChaincodeNames = map[string]struct{}{
		"cscc": {},
		"escc": {},
		"lscc": {},
		"qscc": {},
		"vscc": {},
	}
)

func (i *Invocation) validateInput(name, version string, collections *pb.CollectionConfigPackage) error {
	if !ChaincodeNameRegExp.MatchString(name) {
		return errors.Errorf("invalid chaincode name '%s'. Names can only consist of alphanumerics, '_', and '-' and can only begin with alphanumerics", name)
	}
	if _, ok := systemChaincodeNames[name]; ok {
		return errors.Errorf("chaincode name '%s' is the name of a system chaincode", name)
	}

	if !ChaincodeVersionRegExp.MatchString(version) {
		return errors.Errorf("invalid chaincode version '%s'. Versions can only consist of alphanumerics, '_', '-', '+', and '.'", version)
	}

	collConfigs, err := extractStaticCollectionConfigs(collections)
	if err != nil {
		return err
	}
	// we extract the channel config to check whether the supplied collection configuration
	// complies to the given msp configuration and performs semantic validation.
	// Channel config may change afterwards (i.e., after endorsement or commit of this transaction).
	// Fabric will deal with the situation where some collection configs are no longer meaningful.
	// Therefore, the use of channel config for verifying during endorsement is more

View on GitHub (pinned to 2736b63f8f)

Solutions

Rename the chaincode to match ^[a-zA-Z0-9_-]+$ with a leading alphanumeric
Strip any repository prefixes/paths before packaging and installing the chaincode
Add name normalization in CI before invoking lifecycle commands

Example fix

// before
name := "my.org/asset-transfer"
// after
name := "asset-transfer"

Defensive patterns

Strategy: validation

Validate before calling

// Go
var chaincodeNameRe = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`)
func isValidChaincodeName(name string) bool { return chaincodeNameRe.MatchString(name) }

Try / catch

if !isValidChaincodeName(name) { return fmt.Errorf("invalid chaincode name %q", name) }
// then invoke approve/commit

Prevention

Validate names in CI before packaging chaincode
Strip registry/path prefixes from chaincode names
Document naming rules for chaincode authors

When it happens

Trigger: Submitting a chaincode name with spaces, dots, special characters, or leading underscore/dash via approveformyorg or commit.

Common situations: Using image-like names (e.g. 'my.org/chaincode'), file paths, or names with '@' or uppercase-with-symbols from CI pipelines.

Related errors

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