Troubleshooting guide for ZKsync SDKs

Whether you’re facing integration challenges, encountering unexpected errors, or need clarity on certain functionalities, here are detailed solutions and best practices to ensure a smooth development experience.

JavaScript SDK

If you encounter issues using the JavaScript SDK during the installation, refer to the troubleshooting steps:

  1. Network selection: Ensure you are using the Layer 2 (L2) network instead of Layer 1 (L1) Sepolia. The correct endpoint for the L2 network is: ZKsync Sepolia Explorer.
  2. Transaction hash and block tag: Use the correct transaction hash and block tag when fetching transaction details.


  1. Unable to Install the ZKsync Python SDK
    • Ensure you have Python 3.8 or higher installed. You can download the latest version from the Python website.
    • Make sure you have pip version 23.1.2 or higher. You can upgrade pip by running:
      pip install --upgrade pip
    • Run the installation command:
      pip install zksync2
  2. ImportError: No module named 'zksync2'
    • Verify the installation by running:
      pip show zksync2
      If it is not installed, follow the installation steps in number 1.
    • Ensure your Python script is using the correct Python environment where zksync2 is installed.
  3. Connection Error When Connecting to ZKsync Era
    • Check your internet connection.
    • Ensure you are using the correct operator node endpoint.
      from zksync2.module.module_builder import ZkSyncBuilder
      sdk ="")
    • Verify the endpoint URL is correct and the service is operational.
  4. AttributeError: 'module' object has no attribute 'zksync'
    • Make sure you are using the correct import statements and setup:
      from zksync2.module.module_builder import ZkSyncBuilder
      sdk ="")
    • Ensure you are accessing the attributes correctly.
      chain_id = sdk.zksync.chain_id
  5. Transaction Rejection or Failure
    • Verify that your transaction parameters are correct and meet all the required fields.
    • Ensure your account has sufficient funds for the transaction.
    • Check the gas limit and gas price to ensure they are set appropriately.
    • Review any error messages returned by the transaction to identify specific issues.
  6. Incorrect or Unexpected Response Data
    • Double-check the method you are calling and the parameters you are passing.
    • Ensure that you are handling the response data correctly in your script.
    • Refer to the official documentation and examples to confirm correct usage of the SDK methods.

Made with ❤️ by the ZKsync Community