hyperledger/fabric · error

unmarshalling of ChaincodeData failed, error %s

Error message

unmarshalling of ChaincodeData failed, error %s

What it means

During LSCC (lifecycle system chaincode) validation, the validator unmarshals the first write value from the lscc write-set into a ChaincodeData protobuf. This error means that value is not a valid serialized ChaincodeData message, so Fabric rejects the transaction as a policy violation. It protects the ledger from malformed or tampered lifecycle records.

Source

Thrown at core/handlers/validation/builtin/v13/lscc_validation_logic.go:471

		/* security check 0 - validation of rwset */
		/******************************************/
		// there has to be a write-set
		if lsccrwset == nil {
			return policyErr(fmt.Errorf("No read write set for lscc was found"))
		}
		// there must be at least one write
		if len(lsccrwset.Writes) < 1 {
			return policyErr(fmt.Errorf("LSCC must issue at least one single putState upon deploy/upgrade"))
		}
		// the first key name must be the chaincode id provided in the deployment spec
		if lsccrwset.Writes[0].Key != cdsArgs.ChaincodeSpec.ChaincodeId.Name {
			return policyErr(fmt.Errorf("expected key %s, found %s", cdsArgs.ChaincodeSpec.ChaincodeId.Name, lsccrwset.Writes[0].Key))
		}
		// the value must be a ChaincodeData struct
		cdRWSet := &ccprovider.ChaincodeData{}
		err = proto.Unmarshal(lsccrwset.Writes[0].Value, cdRWSet)
		if err != nil {
			return policyErr(fmt.Errorf("unmarshalling of ChaincodeData failed, error %s", err))
		}
		// the chaincode name in the lsccwriteset must match the chaincode name in the deployment spec
		if cdRWSet.Name != cdsArgs.ChaincodeSpec.ChaincodeId.Name {
			return policyErr(fmt.Errorf("expected cc name %s, found %s", cdsArgs.ChaincodeSpec.ChaincodeId.Name, cdRWSet.Name))
		}
		// the chaincode version in the lsccwriteset must match the chaincode version in the deployment spec
		if cdRWSet.Version != cdsArgs.ChaincodeSpec.ChaincodeId.Version {
			return policyErr(fmt.Errorf("expected cc version %s, found %s", cdsArgs.ChaincodeSpec.ChaincodeId.Version, cdRWSet.Version))
		}
		// it must only write to 2 namespaces: LSCC's and the cc that we are deploying/upgrading
		for _, ns := range txRWSet.NsRwSets {
			if ns.NameSpace != "lscc" && ns.NameSpace != cdRWSet.Name && len(ns.KvRwSet.Writes) > 0 {
				return policyErr(fmt.Errorf("LSCC invocation is attempting to write to namespace %s", ns.NameSpace))
			}
		}

		logger.Debugf("Validating %s for cc %s version %s", lsccFunc, cdRWSet.Name, cdRWSet.Version)

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the deployment/upgrade proposal so lscc produces a correctly serialized ChaincodeData value (use the standard SDK/lifecycle flow, not hand-built rwsets).
2. Check that the peer, SDK, and the code that created the proposal use compatible Fabric/proto versions.
3. Verify the transaction payload was not truncated or re-encoded in transit (e.g. by a proxy or custom ordering logic).
4. If the ledger record itself is corrupt, restore from a checkpoint/snapshot or re-deploy the chaincode on a corrected channel.

Example fix

// before: hand-crafting the lscc value
value := []byte("mychaincode-v1")
// after: serialize a proper ChaincodeData
cd := &ccprovider.ChaincodeData{Name: "mychaincode", Version: "1.0", ...}
value, _ := proto.Marshal(cd)

// before submitting: verify the lscc write value decodes as ChaincodeData
cd := &ccprovider.ChaincodeData{}
if err := proto.Unmarshal(lsccWriteValue, cd); err != nil {
    return fmt.Errorf("lscc value is not a valid ChaincodeData: %v", err)
}

func isChaincodeData(b []byte) bool { cd := &ccprovider.ChaincodeData{}; return proto.Unmarshal(b, cd) == nil && cd.Name != "" }

err := validateLSCC(txRWSet); if err != nil { if strings.Contains(err.Error(), "unmarshalling of ChaincodeData failed") { /* rebuild proposal / regenerate rwset */ } return err }

When it happens

Trigger: Submitting an lscc deploy/upgrade transaction whose rwset writes a value at the chaincode key that is corrupt, truncated, serialized with an incompatible proto schema, or not a ChaincodeData at all.

Common situations: Manually crafted or third-party-modified deployment transactions, cross-version Fabric upgrades where the ChaincodeData proto changed, custom chaincode lifecycle tooling writing raw bytes to the lscc namespace, ledger corruption or a buggy shim implementation.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• failed unmarshalling lscc read value into ChaincodeData
• unmarshalling ChaincodeQueryResponse failed
• invalid collection configuration supplied for chaincode %s:%
• malformed chaincode invocation spec
• unmarshalling of ChaincodeData failed, error %s

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