HOWTO: Debug an outgoing withdrawal

You have configured a full-node wallet or a CoinPayments wallet with the Bitcoin and Altcoin Wallets plugin. A user has attempted a withdrawal but the withdrawal doesn’t work. Here’s how to debug:


The troubleshooting instructions below are for Bitcoin and Altcoin Wallets versions before 6.0.0.

Since Bitcoin and Altcoin Wallets version 6.0.0, these instructions are now found in the built-in documentation, under the Troubleshooting chapter. In your WordPress admin screens, navigate to: Wallets Admin DocswalletsTroubleshooting common issuesThere are withdrawal transactions entered in the system but they do not get processed..

The Troubleshooting chapter of the documentation is also available on github.

Some background

When the user enters a withdrawal request, this is added to a queue of transactions to execute. Once the transaction is placed in the queue, it will be attempted by the cron job for a predetermined number of times (3 by default). After the transaction is executed, the user will be notified by email about the transaction execution. Several things can go wrong. This article will help you to debug the root cause.

Troubleshooting steps:

① Did the user receive an error message via email?

If the transaction was attempted and there was an error, such as insufficient funds, the user would have received an error over email. The error substitutes the ###LAST_ERROR### part of the email template. The error will contain a useful message, hinting as to what went wrong. The error can come from the full node wallet itself or from the plugin. Inspect the error or contact me about it to figure out what’s going on.

If you are not sure whether emails are being sent from your WordPress installation at all, use a plugin to test. For example, you can install this plugin, then go to ToolsTest Email to use the checker. If emails are not being sent at all, then users would not be receiving notifications about any potential errors. Fix email sending before debugging withdrawals. Your hosting provider may be able to help you with this.

② Has the transaction been verified by the user and an admin?

By default, withdrawals require the user to verify them over an email link, and the admin has to also verify the transaction via the Transactions list screen. This behavior can be toggled in WalletsConfirmsWithdraw transaction confirmations.

To check if a withdrawal has been cleared by both the user and an admin, go to the WalletsTransactions admin screen. Find the user’s withdrawal. Under “Accepted by admin” and “Verified by User” you should see a ticked checkbox (☑). If the box is empty (☐), this means that either the admin or the user has not allowed the transaction to proceed. Once all required verifications are provided, the transaction will progress to “pending” status on the next cron heartbeat.

③ Are the cron jobs running?

The plugin performs a number of periodic tasks (cron jobs), and one of them is the processing of withdrawals. If cron jobs are not running, no transactions will be executed.

If the transaction is stuck in an “unconfirmed” status and with 3 retries, it may be that cron jobs are not running. To check:

  1. Go to WalletsCron job and check the settings. By default, the cron job runs “Every minute”, with a batch size of 8 (i.e. execute up to eight transactions on each cron), and withdrawals are retried for a maximum of 3 times before being marked as “failed”. If unsure, revert these values to their defaults.
  2. Go to the admin dashboard, under “Bitcoin and Altcoin Wallets”. Note the value shown next to “Cron jobs last ran on”. This is the last time that a cron job has run, and therefore the last time when withdrawals were attempted.

Another way to debug cron jobs is the following: You can install the plugin WP Crontrol, then go to Tools Crontab. This will show you a diagnostic for cron jobs. If there is any problem with WP Cron, the problem will be shown here. For example, if you are getting a curl error “connection refused”, then you may need to add your server’s domain name and IP in your server’s /etc/hosts file. Your host may be able to help you with this.

If you have determined that cron jobs are not running, you can try triggering the cron jobs manually. Go to WalletsCron job and find the trigger URL. The trigger URL contains a secret that is unique to this installation. Follow the link to trigger the cron job, then check the status and retry count of the withdrawal again to see if anything changes.

④ Is the adapter locked? (full node wallets only)

If you have encrypted your full node wallet with a passphrase, then the wallet will be locked until you provide the passphrase.

To check if the wallet is locked, go to WalletsAdapters and find the adapter corresponding to the coin of your withdrawal. Note the value of “Withdrawals lock”.

If the wallet is unlocked, an open padlock will be shown (?). This means that the wallet is either not encrypted, or the passphrase has been provided. In this case, withdrawals can be performed.

If the wallet is encrypted with a passphrase, and the plugin does not have the passphrase, then a closed padlock will be shown (?) and withdrawals for this adapter will not be attempted.

To provide a passphrase, do the following:

  1. In WalletsCron jobTime to retain withdrawal secrets, enter the amount of minutes that you wish the passphrase to be retained for. The plugin will unlock wallets for the specified number of minutes after a passphrase is entered, and will not save the passphrase. If you enter the value 0, then the plugin will save the passphrase indefinitely and use the passphrase whenever it needs to unlock the wallet. (This is obviously a less secure option because the passphrase has to be stored on the WordPress DB.)
  2. In the coin adapter settings, under Wallets → (full node adapter) → Daemon RPC APIWallet passphrase, enter your passphrase and hit “Save Changes”. The passphrase will be used to unlock the wallet. Check again to see that the padlock icon is now opened in to the adapters list. While the padlock is open, withdrawals will be attempted by any cron jobs that run.

⑤ Have you set withdrawal fees correctly? (full node wallets only)

Every full node wallet can accept arguments (conf entries) to specify the amount to be spent on outgoing transactions. For Bitcoin and friends, these include paytxfee and mintxfee. For a complete reference consult your wallet’s manual, and/or the following page:

If you have set withdrawal fees too low, transactions would be failing. Normally your users will be receiving error messages about this and withdrawals will be failing. To fix this, go to the coin adapter settings, and modify the Fixed part of withdrawal fee to a value that is sensible for your coin.

⑥ Are there any errors in the wallet’s logs? (full node wallets only)

If you got up to here and your full node wallet still does not process withdrawals, it’s worth checking the wallet’s log file. The log file for bitcoin core is at ~/.bitcoin/debug.log. (See here.) For other wallets the location will be similar, e.g. ~/.litecoin/debug.log, etc.

⑦ Have you set withdrawal fees correctly? (CoinPayments adapter only)

If you are using the CoinPayments adapter, withdrawal fees are specified differently. Go to WalletsCoinPaymentsCoin Settings and fees. Save the page once without altering any settings. This has the effect that, if any value under “Withdrawal fee (fixed)” is lower than what the CoinPayments platform allows, that value is increased to the necessary minimum. If this was the problem, then you can now retry your withdrawal.

⑧ Is the withdrawal being propagated to CoinPayments for execution?

Log in to your CoinPayments account and see if the withdrawal is being transmitted to CoinPayments. The withdrawal should be under Transaction HistoryWithdrawal History. You can check the Status of the Withdrawal.

If all else fails, ask for help!

This article didn’t help? Are you still encountering problems with withdrawals?

Please use the support forum for the full node adapter or the support forum for the CoinPayments adapter. Let me know what you have checked and what you found. You can also contact me by email.


Leave a Reply

Your email address will not be published.