{"record":{"id":"f7a8dce73515e6df","repo":"hyperledger/fabric","slug":"transaction-returned-with-failure-s","errorCode":null,"errorMessage":"transaction returned with failure: %s","messagePattern":"transaction returned with failure: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/chaincode/chaincode_support.go","lineNumber":196,"sourceCode":"\t\treturn nil, nil, errors.Errorf(\"nil response from transaction %s\", txid)\n\t}\n\n\tif resp.ChaincodeEvent != nil {\n\t\tresp.ChaincodeEvent.ChaincodeId = ccName\n\t\tresp.ChaincodeEvent.TxId = txid\n\t}\n\n\tswitch resp.Type {\n\tcase pb.ChaincodeMessage_COMPLETED:\n\t\tres := &pb.Response{}\n\t\terr := proto.Unmarshal(resp.Payload, res)\n\t\tif err != nil {\n\t\t\treturn nil, nil, errors.Wrapf(err, \"failed to unmarshal response for transaction %s\", txid)\n\t\t}\n\t\treturn res, resp.ChaincodeEvent, nil\n\n\tcase pb.ChaincodeMessage_ERROR:\n\t\treturn nil, resp.ChaincodeEvent, errors.Errorf(\"transaction returned with failure: %s\", resp.Payload)\n\n\tdefault:\n\t\treturn nil, nil, errors.Errorf(\"unexpected response type %d for transaction %s\", resp.Type, txid)\n\t}\n}\n\n// Invoke will invoke chaincode and return the message containing the response.\n// The chaincode will be launched if it is not already running.\nfunc (cs *ChaincodeSupport) Invoke(txParams *ccprovider.TransactionParams, chaincodeName string, input *pb.ChaincodeInput) (*pb.ChaincodeMessage, error) {\n\tccid, cctype, err := cs.CheckInvocation(txParams, chaincodeName, input)\n\tif err != nil {\n\t\treturn nil, errors.WithMessage(err, \"invalid invocation\")\n\t}\n\n\th, err := cs.Launch(ccid)\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/chaincode/chaincode_support.go#L178-L214","documentation":"When the chaincode message type is ChaincodeMessage_ERROR, processChaincodeExecutionResult converts it into this Go error whose text contains the raw payload from the chaincode. It means the chaincode itself reported the transaction failed (e.g. shim.Error was called or the chaincode panicked) — this is not a peer infrastructure failure. The payload bytes are interpolated directly into the message.","triggerScenarios":"The invoked chaincode returns an error response via shim.Error(...), calls panic, or its handler emits ChaincodeMessage_ERROR; Execute/ExecuteLegacyInit then surfaces 'transaction returned with failure: <payload>'.","commonSituations":"Application-level validation failures in chaincode logic (bad key, insufficient balance); chaincode panics due to nil pointers or unmarshaling bad input; calling a chaincode before it was initialized in pre-2.0 style; explicit access-control rejections inside chaincode.","solutions":["Read the payload text embedded in the error — it comes from the chaincode's shim.Error message and pinpoints the failure.","Fix the application/chaincode logic that generated the error (invalid arguments, missing state, permission checks).","If it's a panic, check chaincode container logs for a stack trace and add recovery/argument validation.","Verify the client sends the expected arguments (correct number, types, JSON shape) for the invoked function."],"exampleFix":"// before: chaincode panics on missing arg\nargs := stub.GetStringArgs()\nkey := args[1] // panic -> ERROR message\n// after: validate and return a clean error\nif len(args) < 2 {\n    return shim.Error(\"expected key argument\")\n}\nkey := args[1]","handlingStrategy":"try-catch","validationCode":"// validate arguments before invoking to avoid chaincode-level rejections\nif len(args) == 0 || args[0] == \"\" {\n    return fmt.Errorf(\"function name required\")\n}\nif err := validateFcnArgs(args[0], args[1:]); err != nil {\n    return fmt.Errorf(\"invalid args for %s: %w\", args[0], err)\n}","typeGuard":"func isChaincodeReportedFailure(err error) bool {\n    return err != nil && strings.HasPrefix(err.Error(), \"transaction returned with failure:\")\n}","tryCatchPattern":"_, _, err := chaincodeSupport.Execute(txParams, ccName, input)\nif err != nil {\n    var ccErr string\n    if strings.HasPrefix(err.Error(), \"transaction returned with failure: \") {\n        ccErr = strings.TrimPrefix(err.Error(), \"transaction returned with failure: \")\n        return fmt.Errorf(\"chaincode rejected tx %s: %s\", txParams.TxID, ccErr)\n    }\n    return err\n}","preventionTips":["Read the payload embedded in the error — it is the chaincode's own error message.","Validate all invoke arguments (count, type, format) in the client before submitting.","Add defensive checks and panic recovery in chaincode functions.","Check chaincode container logs (`docker logs <cc-container>`) for stack traces on recurring failures."],"tags":["chaincode","transaction-failure","hyperledger-fabric"],"backgroundTag":"chaincode-transaction-failed","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}