hyperledger/fabric · error

invalid chaincode name: %q

Error message

invalid chaincode name: %q

What it means

ValidateCC checks that the ChaincodeData name embedded in the package is a printable string. Protobuf can deserialize garbage bytes into odd values, so the library rejects non-printable names. This indicates the package bytes did not decode into a meaningful ChaincodeData.

Source

Thrown at core/common/ccprovider/sigcdspackage.go:202

		return errors.New("uninitialized package")
	}

	if ccpack.sDepSpec.ChaincodeDeploymentSpec == nil {
		return errors.New("signed chaincode deployment spec cannot be nil in a package")
	}

	if ccpack.depSpec == nil {
		return errors.New("chaincode deployment spec cannot be nil in a package")
	}

	// 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 := &SignedCDSData{}
	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

1. Repackage the chaincode with a valid, printable chaincode name (letters, digits, dashes)
2. Check that the package file was not corrupted in transit (compare checksums)
3. Ensure you are loading a signed CDS package, not another envelope type

Example fix

// before
name := "\x00bad\nname"
// after
name := "mycc" // printable, valid chaincode name

func validCCName(name string) bool {
    if name == "" { return false }
    for _, r := range name {
        if !unicode.IsPrint(r) { return false }
    }
    return true
}

func isPrintableName(c *pb.ChaincodeData) bool {
    return c != nil && validCCName(c.Name)
}

cd, err := GetCCPackage(buf, idFunc)
if err != nil {
    if strings.Contains(err.Error(), "invalid chaincode name") {
        return fmt.Errorf("package file corrupt; repackage the chaincode: %w", err)
    }
    return err
}

When it happens

Trigger: GetCCPackage -> ValidateCC on a package where ccdata.Name contains non-printable/control characters, typically because the bytes were unmarshaled into the wrong message type.

Common situations: Corrupted or truncated package files; packages produced by buggy custom tooling; feeding an unrelated protobuf envelope to the package loader.

Related errors

• unknown operation type
• signed chaincode deployment spec cannot be nil in a package
• chaincode deployment spec cannot be nil in a package
• invalid chaincode data %v (%v)
• failed to unmarshal envelope from bytes

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