Debug checkSig/checkPreimage Failures

When developing and debugging sCrypt contracts, checkSig and checkPreimage errors are among the most common and troublesome issues. Although the debugger can help pinpoint the exact location of the error in the source code, figuring out why it failed and how to fix it is generally difficult. Today we are going to talk about how to quickly debug and fix these two types of errors¹.

checkPreimage Failure

Let us take the tokenUtxo contract in the boilerplate project as an example. Its debugging configuration is located in .vscode/launch.json. (Some values are omitted for ease of exposition).

Execution failed with error SCRIPT_ERR_NULLFAIL. Stacktrace:   /Users/hero/work/boilerplate/contracts/tokenUtxo.scrypt:14:in 'Token.split'
----- CheckPreimage Fail Hints Begin -----
You should check the differences in detail listed below:
Fields with difference | From preimage in entry method params | From preimage calculated with tx
md5(scriptCode) | 148dd2b3fcc09d6baf15c9fcf5d961d3 | 6393778445f442466414464ee3be7cc7
Preimage calculated with tx:
----- CheckPreimage Fail Hints End -----

checkSig Failure

Another common error is failure when calling checkSig, which is usually caused by a wrong signature.

Execution failed with error SCRIPT_ERR_NULLFAIL.
/Users/hero/work/boilerplate/contracts/tokenUtxo.scrypt:25:in 'Token.split'

----- CheckSig Fail Hints Begin -----
You should make sure the following check points all passed:
1. private key used to sign should be corresponding to the public key 028f46cb8ec957dcda049ac549fc46d451e0095a5b6f95950bc58830a7dc21167c
2. the preimage of the tx to be signed should be 0100000028bcef7e73248aa273...
----- CheckSig Fail Hints End -----
  1. Check whether the preimage of the transaction to be signed (automatically calculated base on txContext) is consistent with the passed parameters.
Preimage JSON


Original article is by Yiqiang Wang and translation is drafted by Hongfeng Zheng.

sCrypt Inc ( is a company with mission to providing integrated on-chain smart contracting solutions on Bitcoin SV.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store