What causes "chaincode name '%s' is the name of a system chaincode" in hyperledger/fabric?

Choose a user chaincode name that does not collide with any system chaincode name

chaincode name '%s' is the name of a system chaincode

Error message

chaincode name '%s' is the name of a system chaincode

What it means

validateInput rejects chaincode names that collide with system chaincode names (such as _lifecycle, cscc, qscc, escc, vscc) to prevent shadowing or confusing built-in SCCs. This is a reserved-name guard, not a format error.

Source

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

	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
	// towards catching manual errors in the config as oppose to any attempt of serializability.
	channelConfig := i.SCC.ChannelConfigSource.GetStableChannelConfig(i.ChannelID)
	if channelConfig == nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

Choose a user chaincode name that does not collide with any system chaincode name
If testing lifecycle itself, use a prefixed name like 'test-lifecycle-cc'

Example fix

// before
name := "_lifecycle"
// after
name := "my_lifecycle_cc"

Defensive patterns

Strategy: validation

Validate before calling

// Go
var reserved = map[string]bool{"cscc":true,"qscc":true,"escc":true,"vscc":true,"_lifecycle":true}
func isReservedName(name string) bool { return reserved[name] }

Try / catch

if isReservedName(name) { return fmt.Errorf("name %q is reserved", name) }
// then invoke lifecycle APIs

Prevention

Maintain a reserved-name list in tooling that fails fast
Prefix test chaincodes to avoid SCC name collisions
Review naming before adding new system chaincodes

When it happens

Trigger: Approving or committing a user chaincode whose name matches an entry in the systemChaincodeNames map (e.g. '_lifecycle').

Common situations: Developers experimenting with lifecycle internals naming their chaincode '_lifecycle' or 'qscc', or test fixtures reusing SCC names.

Related errors

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