Skip to content
Related Articles
Open in App
Not now

Related Articles

Error Handling in Hyperledger Fabric

Improve Article
Save Article
  • Last Updated : 02 Jan, 2023
Improve Article
Save Article

Error handling refers to the response and recovery procedures from the error conditions present in the software application. The clarity of the error messages and the options provided to users for fixing the issue determine the quality of such processes. Error handling comprises of anticipation, detection, and resolution of application errors, communication errors, etc. The article focuses on discussing error handling in hyperledger fabric.

Importance of Error Handling

Both software and hardware errors can be gracefully handled with error handling, and execution can be resumed when interrupted with error handling. When it comes to software error handling, the programmer either creates the necessary codes or employs software tools to handle errors. There are only two main purposes why error handling is important.

  1. Helps to anticipate errors in advance: Error handling helps to anticipate the errors in advance so that an appropriate code can be used to recover from them.
  2. To ensure a graceful exit: It might not be possible to handle all errors and exceptions but it may be possible to program software in such a way that in case of error, the system can exit gracefully instead of causing any major issues, security vulnerabilities, etc. For example, it is always better to see a popup message “There has been an issue. Please contact the support team” instead of a technical error message “Object not set to reference of an object” and eventual system crash.
  3. To maintain resilient architecture: Good error handling is very important for planning and maintaining a resilient architecture. It is not a good practice that the system crashes every time even on a small error condition. 

Types of Error in Blockchain Network

Errors in blockchain networks fall into 2 categories:

  1. Retryable error: These are the type of errors that should be propagated back to the application layer for error handling and a retry mechanism. This means that the entire transaction can be retried in response to the error.
  2. Nonretryable error: These types of errors are due to incorrect usage and should be handled properly leading to the graceful exit of the code path.

Common Errors in Hyperledger Fabric

Below are some of the common error types in hyperledger fabric:

Error Type  Description Mitigation Recommended Handling
grpc request timeout while submitting the proposal Timeout happens at any stage of the blockchain transaction flow. When the time taken to execute the proposal exceeds the configured execution time default of 30 seconds then the error occurs. To mitigate the issue increase the execution timeout if there is complex or lengthy computation to be done in the smart contract.

1. Set CORE_CHAINCODE_EXECUTETIMEOUT =<60s or higher> in Fabric configuration.

2. Set gRPC settings at the Fabric client end to increase gRPC timeout-

“grpc.keepalive_time_ms”: 120000,
“grpc.http2.min_time_between_pings_ms”: 120000,
“grpc.keepalive_timeout_ms”: 20000,

3. Handle the timeout exception at the client side by writing the retry logic on the client side.

4. Check peer health and health of IO operations at peer and restart if the peer is not healthy.

MVCC_READ_CONFLICT  This error is typically seen during committing the transaction. If during the time between read-write set creation and committing the transaction, a different transaction was committed and changed the version of the key in the peer’s world state, then the original transaction is rejected as the version when read is not the current version. The application needs to avoid key collisions.

1. Create data and transaction structures that avoid changing the same key concurrently.

2. Write retry logic on the client side to avoid key collisions.

If(validationCode == 11) {

   // a is object on ledger
   Object a = // query the ledger again for the latest state
   // perform the write on  object a
   a.setAction() }

Peer lag 
  1. P1 and P2 are two peers.
  2. K1 is a new key added to the ledger.
  3. Due to network latency K1 is not added to P2’s ledger.
  4. The application queried for Ki on P2.
  5. Receives null value.
Program application to identify and handle inconsistent data caused by peer lag. In case of null values are returned, implement the retry logic to ascertain the state update. 
Endorsement Policy failures The endorsement of the transaction may fail due to multiple reasons like technical reasons, invalid endorser signatures, misconfigurations, or transient world state inconsistencies between peers. Validate the configurations and correct them.

1. The application can change the endorsement policy based on its logic.

2. In case of misconfigurations, validate and correct the configurations.

3. In case of world inconsistencies, write a client-side retry logic.

Chaincode errors Chaincode to chaincode communication error due to the unavailability of a particular chaincode on a given channel or the dependent chaincode unable to accept the requests. Exponential backoff for recovery.

1. Unique error codes can be propagated by the caller chaincode.

2. Client applications can be programmed to identify and categorize errors as retriable errors. 

Instantiate-chaincode-Error: ChannelEventHub has been shutdown eventhub will get disconnected when it finds more than one chaincode version. Reinstall and instantiate the chaincode. Recommended handling is to kill all the containers and keep the last and latest version of the chaincode and then try to install and instantiate the chaincode.
Instantiate-chaincode-Instantiate proposal was bad This error occurs at the time of instantiating the chaincode. Chaincode instantiation mostly fails in syntax checking and logical issues in chaincode. Fix the errors.

Run the command:

docker logs -f 

to see the clear logs, where the errors are being thrown, fix the errors, reinstall and instantiate the chaincode.

Chaincode already exists  This error occurs when the system thinks that the chaincode already exists. Kill docker images, stop fabric, start fabric again, and start deploying the business network card again.

Use the following commands:



Connection fail Error trying to ping and Composer runtime is not compatible with client. Stop fabric.

Use the following commands:


npm install-g composer-playground@0.19.8


Connection refused Failed to connect to localhost port. This error occurs when user builds its own docker and tries to execute it.

Use the command:

docker run — rm -i -t -p 49160:8080 <your username>/node-app

Error Handling Framework

The new error-handling framework should be used in place of the existing calls to fmt.Errorf() or Error() and ErrorWithCallstack() can be used.

Error(componentcode string, reasoncode string, message string, args…) CallStackError
ErrorWithCallstack(componentcode string, reasoncode string, message string, args…) CallStackError


The existing call using Errorf():

fmt.Errorf(“Error trying to connect to local peer: %s”, err.Error())

can be converted to:

err = errors.Error(“Peer”, “ConnectionError”, “Error trying to connect to local peer: %s”, err.Error())


err = errors.ErrorWithCallstack(“Peer”, “ConnectionError”, “Error trying to connect to local peer: %s”, err.Error())

Callstack is beneficial for critical errors. Here,

Peer: Component name

ConnectionError: Error message name

Error trying to connect to local peer: %s: Error message and arguments to format the message.

Functions in CallStackError Interface

Below are some of the functions in the CallStackError Interface:

  • GetStack() string: Gets the call stack.
  • GetErrorCode() string: Gets the error code as a pre-formatted string.
  • GetComponentCode() string: Gets the component code that describes the originating module/ component.
  • GetReasonCode() string: Gets the reason code which describes the lower-level reason for the error.                                                                                                                            

My Personal Notes arrow_drop_up
Related Articles

Start Your Coding Journey Now!