What causes "invalid chaincode name: %q" in hyperledger/fabric?

Sanitize the chaincode name before packaging — allow only printable, valid chaincode-name characters

invalid chaincode name: %q

Error message

invalid chaincode name: %q

What it means

ValidateCC rejects ChaincodeData whose Name contains non-printable characters using this error. Because protobuf will happily deserialize garbage, the package layer sanity-checks the name before LSCC sees it; non-printable names indicate corrupted or fabricated chaincode data.

Source

Thrown at core/common/ccprovider/cdspackage.go:159

// ValidateCC returns error if the chaincode is not found or if its not a
// ChaincodeDeploymentSpec
func (ccpack *CDSPackage) ValidateCC(ccdata *ChaincodeData) error {
	if ccpack.depSpec == nil {
		return errors.New("uninitialized package")
	}

	if ccpack.data == nil {
		return errors.New("nil data")
	}

	// This is a hack. LSCC expects a specific LSCC error when names are invalid so it
	// has its own validation code. We can't use that error because of import cycles.
	// Unfortunately, we also need to check if what have makes some sort of sense as
	// protobuf will gladly deserialize garbage and there are paths where we assume that
	// a successful unmarshal means everything works but, if it fails, we try to unmarshal
	// into something different.
	if !isPrintable(ccdata.Name) {
		return fmt.Errorf("invalid chaincode name: %q", ccdata.Name)
	}

	if ccdata.Name != ccpack.depSpec.ChaincodeSpec.ChaincodeId.Name || ccdata.Version != ccpack.depSpec.ChaincodeSpec.ChaincodeId.Version {
		return fmt.Errorf("invalid chaincode data %v (%v)", ccdata, ccpack.depSpec.ChaincodeSpec.ChaincodeId)
	}

	otherdata := &CDSData{}
	err := proto.Unmarshal(ccdata.Data, otherdata)
	if err != nil {
		return err
	}

	if !proto.Equal(ccpack.data, otherdata) {
		return errors.New("data mismatch")
	}

	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Sanitize the chaincode name before packaging — allow only printable, valid chaincode-name characters
Regenerate/reinstall the package from trusted source since data is likely corrupted
Verify the bytes were not mangled by encoding/transfer issues
Inspect the quoted name (%q) in the error to identify the corruption source

Example fix

// before
name := "my\x00cc" // control char embedded
ccdata.Name = name
// after
if !isPrintable(name) { return fmt.Errorf("invalid chaincode name %q", name) }
ccdata.Name = "mycc"

Defensive patterns

Strategy: validation

Validate before calling

func validChaincodeName(name string) bool {
    if name == "" { return false }
    for _, r := range name {
        if r < 0x20 || r == 0x7f { return false } // non-printable
    }
    return true
}

Type guard

func isPrintableName(ccdata *ccprovider.ChaincodeData) bool {
    return ccdata != nil && validChaincodeName(ccdata.Name)
}

Try / catch

if err := ccpack.ValidateCC(ccdata); err != nil {
    if strings.HasPrefix(err.Error(), "invalid chaincode name") {
        return fmt.Errorf("rejecting package: %w", err)
    }
    return err
}

Prevention

Validate user-supplied chaincode names (alnum/dash) before packaging
Checksum package files to detect corruption early
Never build ChaincodeData from untrusted raw bytes without sanitizing
Fuzz/validate input paths that deserialize external buffers

When it happens

Trigger: Calling ValidateCC (directly or via GetCCPackage/InitFromPath) with a ChaincodeData whose Name field contains non-printable/control characters — corrupt protobuf bytes deserialized as garbage, or malicious input.

Common situations: Corrupted package files on disk; an attacker-supplied or fuzzed package buffer; string mangled by encoding issues before packaging.

Related errors

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