hyperledger/fabric · error

error unmarshalling ChaincodeActionPayload

Error message

error unmarshalling ChaincodeActionPayload

What it means

UnmarshalChaincodeActionPayload wraps proto.Unmarshal failures for peer.ChaincodeActionPayload bytes with this message. It is thrown when the input bytes are not a valid ChaincodeActionPayload protobuf. Typically the caller extracted the wrong slice of the transaction payload (e.g. did not unwrap the TransactionActions first).

Source

Thrown at protoutil/unmarshalers.go:165

// UnmarshalProposal unmarshals bytes to a Proposal
func UnmarshalProposal(propBytes []byte) (*peer.Proposal, error) {
	prop := &peer.Proposal{}
	err := proto.Unmarshal(propBytes, prop)
	return prop, errors.Wrap(err, "error unmarshalling Proposal")
}

// UnmarshalTransaction unmarshals bytes to a Transaction
func UnmarshalTransaction(txBytes []byte) (*peer.Transaction, error) {
	tx := &peer.Transaction{}
	err := proto.Unmarshal(txBytes, tx)
	return tx, errors.Wrap(err, "error unmarshalling Transaction")
}

// UnmarshalChaincodeActionPayload unmarshals bytes to a ChaincodeActionPayload
func UnmarshalChaincodeActionPayload(capBytes []byte) (*peer.ChaincodeActionPayload, error) {
	cap := &peer.ChaincodeActionPayload{}
	err := proto.Unmarshal(capBytes, cap)
	return cap, errors.Wrap(err, "error unmarshalling ChaincodeActionPayload")
}

// UnmarshalChaincodeProposalPayload unmarshals bytes to a ChaincodeProposalPayload
func UnmarshalChaincodeProposalPayload(bytes []byte) (*peer.ChaincodeProposalPayload, error) {
	cpp := &peer.ChaincodeProposalPayload{}
	err := proto.Unmarshal(bytes, cpp)
	return cpp, errors.Wrap(err, "error unmarshalling ChaincodeProposalPayload")
}

// UnmarshalTxReadWriteSet unmarshals bytes to a TxReadWriteSet
func UnmarshalTxReadWriteSet(bytes []byte) (*rwset.TxReadWriteSet, error) {
	rws := &rwset.TxReadWriteSet{}
	err := proto.Unmarshal(bytes, rws)
	return rws, errors.Wrap(err, "error unmarshalling TxReadWriteSet")
}

// UnmarshalKVRWSet unmarshals bytes to a KVRWSet
func UnmarshalKVRWSet(bytes []byte) (*kvrwset.KVRWSet, error) {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Confirm the input is Transaction.Actions[i].Payload (ChaincodeActionPayload level), not the outer Payload or the ProposalResponsePayload
2. Check the byte slice is non-empty and not truncated before calling
3. Verify fabric-protos version alignment between writer and reader of the bytes
4. Handle the error path gracefully: treat the transaction as invalid (as Fabric validation code does) rather than retrying

Example fix

// before
cap, err := protoutil.UnmarshalChaincodeActionPayload(payloadBytes) // wrong level
// after
tx, _ := protoutil.UnmarshalTransaction(env.Payload)
if len(tx.Actions) == 0 { return errors.New("no transaction actions") }
cap, err := protoutil.UnmarshalChaincodeActionPayload(tx.Actions[0].Payload)

func extractCAP(tx *peer.Transaction, idx int) ([]byte, bool) {
    if tx == nil || idx >= len(tx.Actions) || len(tx.Actions[idx].Payload) == 0 {
        return nil, false
    }
    return tx.Actions[idx].Payload, true
}

func safeUnmarshalCAP(b []byte) (cap *peer.ChaincodeActionPayload, ok bool) {
    cap, err := protoutil.UnmarshalChaincodeActionPayload(b)
    return cap, err == nil && cap != nil
}

cap, err := protoutil.UnmarshalChaincodeActionPayload(actionBytes)
if err != nil {
    return nil, status.Errorf(codes.InvalidArgument, "malformed chaincode action payload: %v", err)
}

When it happens

Trigger: Calling UnmarshalChaincodeActionPayload with the full payload instead of Transaction.Actions[0].Payload, empty/nil bytes, truncated CAP bytes, or bytes produced by mismatched proto versions.

Common situations: Transaction validators (Validate, validateEndorserTransaction) processing a tampered or malformed block, or tooling that unpacks the wrong nesting level of an endorser transaction.

Related errors

• error unmarshalling
• error unmarshalling original config
• error unmarshalling updated config
• failed to unmarshal ApplicationPolicy bytes
• could not unmarshal signature policy envelope

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