invalid chaincode version '%s'. Versions can only consist of

Error message

invalid chaincode version '%s'. Versions can only consist of alphanumerics, '_', '-', '+', and '.'

What it means

Returned by lifecycle validateInput when the chaincode version fails ChaincodeVersionRegExp — it contains characters outside alphanumerics, '_', '-', '+', and '.'. The version string is part of the definition being approved/committed and is validated before any state is written.

Source

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

	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
	// towards catching manual errors in the config as oppose to any attempt of serializability.
	channelConfig := i.SCC.ChannelConfigSource.GetStableChannelConfig(i.ChannelID)
	if channelConfig == nil {
		return errors.Errorf("could not get channelconfig for channel '%s'", i.ChannelID)
	}
	mspMgr := channelConfig.MSPManager()
	if mspMgr == nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

Sanitize the version string to match the allowed character set before invoking lifecycle commands
Map git/docker tags to a compliant version (e.g. 'v1.0-beta' instead of 'v1.0/beta')
Add a CI check validating the version before approve/commit

Example fix

// before
version := "1.0.0/release"
// after
version := "1.0.0-release"

Defensive patterns

Strategy: validation

Validate before calling

// Go
var chaincodeVersionRe = regexp.MustCompile(`^[a-zA-Z0-9_.+-]+$`)
func isValidChaincodeVersion(v string) bool { return chaincodeVersionRe.MatchString(v) }

Try / catch

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

Prevention

Sanitize CI-generated versions derived from git/docker tags
Replace '/' and ':' in tags with '-' before use as version
Add a lint step validating version format

When it happens

Trigger: Approving/committing with versions containing spaces, slashes (e.g. 'v1.0/beta'), or other unsupported characters.

Common situations: Deriving versions from git tags or Docker tags that include '/', ':', or other characters, and passing them unmodified as the chaincode version.

Related errors

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