This document covers the most common questions and issues that may occur during BTCPay sync.
After deployment, your BTCPay Server needs to sync the entire blockchain and validate all the consensus rules. Depending on your machine specification, bandwidth and number of altcoins you added, this process may take between 1-5 days.
It may seem tedious, but it's a critical step of running your own full node and not having to trust or rely on anyone. Your node will not only download 200GB of data (less if you're using a pruned node) but also validate all the rules of the consensus. You can find more information about the importance of blockchain synchronization in this video.
You can't skip synchronization, but you can drastically decrease sync time. If you're comfortable with using the command line, you can use FastSync to synchronize your node faster. Be sure to read this FastSync document to understand the potential trust issues involved with FastSync.
To use FastSync, make sure your deployment has a pruning option enabled by using an
opt-save-storage environment variable, otherwise bitcoind will not be able to sync. First step is to ssh into your BTCPayServer instance and run the following commands:
sudo su -cd $BTCPAY_BASE_DIRECTORY/btcpayserver-docker/btcpay-down.shcd contrib/FastSync./load-utxo-set.sh# Once FastSync has completedbtcpay-up.sh
After FastSync is complete and you have brought back up your instance, refresh your BTCPay domain and wait for remaining blockchain synchronization. You can also follow this video.
If your FastSync returns:
You need to delete your Bitcoin Core wallet after you load the uxto set, or you find this error:
Last wallet synchronisation goes beyond pruned data it means that the bitcoin core wallet was created before FastSync and needs to be removed (likely because btcpayserver started without the utxoset at the first boot). WARNING: Do not delete this wallet if you have any funds on it. (For example, this may be the case if you use Eclair or FullyNoded to receive funds). If you agree to remove the wallet to finish syncing with FastSync, use
docker volume rm generated_bitcoin_wallet_datadir before you run
When you do not see a pop-up message in the bottom right corner, which shows the sync progress, that means that your server is fully synced and you can begin using it.
Synchronizing a Full Bitcoin node should take between 1 and 3 days.
If this is not the case:
Not enough CPU
We recommend 2 CPU while synchronizing; however some hosting providers throttle your CPU if you use too much.
sudo su -docker stats
If you see more than 100% CPU usage, while being very slow to sync:
8e7ac41e6e2a btcpayserver_bitcoind 100% 560.5MiB / 3.853GiB 14.20% 4.17
Then you need to scale up your machine specification.
If you see very low CPU usage (less than 10%) during synchronization:
8e7ac41e6e2a btcpayserver_bitcoind 10% 560.5MiB / 3.853GiB 14.20% 4.17
Then your hosting provider might throttle your CPU. Please make sure your host supports the high use of CPU for an extended period.
If they don't allow it, shut down your server until they stop throttling you. Then you can limit the CPU via docker, and restart the server:
docker update btcpayserver_bitcoind --cpus ".8"
If you are synching and don't have enough memory, your server may use swap to continue operating:
sudo su -df -h
If you see swap usage:
total used free shared buff/cache availableMem: 2.0G 2.0G 0M 66M 0G 0MSwap: 1.0G 200M 800M
Then it means you need to scale up your server by adding more memory.
Your bitcoin data directory is corrupted
You do not have enough RAM
You do not have enough storage
Check the logs of your node:
sudo su -docker logs --tail 10 btcpayserver_bitcoind
If you see:
Please restart with -reindex or -reindex-chainstate to recover.
Then your bitcoin data directory has been corrupted. It may be physical damage or failure of the hard drive. To reindex your node:
btcpay-down.sh# Delete 'blocks' and 'chainstate' foldersrm -rf /var/lib/docker/volumes/generated_bitcoin_datadir/_data/blocksrm -rf /var/lib/docker/volumes/generated_bitcoin_datadir/_data/chainstatebtcpay-up.sh
Check your RAM:
sudo su -free -h
If you see that you have no
free or very little
total used free shared buff/cache availableMem: 2.0G 2.0G 0M 66M 0G 0MSwap: 0B 0B 0B
Then you need more memory. If you have already synched your node, you can add some swap. If you have not yet synched, your server specs are too limited.
If you already synched, you can add 2G of swap with:
fallocate -l 2G /mnt/swapfilechmod 600 /mnt/swapfilemkswap /mnt/swapfileswapon /mnt/swapfileecho "/mnt/swapfile none swap sw 0 0" >> /etc/fstab
Check the storage of your machine:
sudo su -df -h
If you see you don't have any storage left (/dev/sda1 in my case)
Filesystem Size Used Avail Use% Mounted onudev 2.0G 0 2.0G 0% /devtmpfs 395M 41M 354M 11% /run/dev/sda1 125G 125G 0G 100% /tmpfs 2.0G 0 2.0G 0% /dev/shmtmpfs 5.0M 0 5.0M 0% /run/locktmpfs 2.0G 0 2.0G 0% /sys/fs/cgroup/dev/sdb1 7.8G 18M 7.4G 1% /mnt
Choose the docker fragment for the amount of storage you aim to keep.
Then prune your node.
Yes you can! However, before you do that, you'll want to stop bitcoind from updating docker's volume for it, as that job will be taken over by BTCPayServer.
If you want to run BTCPay inside a docker-compose, and that you have the data directory (
.bitcoin) of a fully synched node on your docker host, then you can reuse it easily for BTCPay.
To do that, follow the following steps :
Do the normal setup according to this instruction.
btcpay-setup.sh is over, turn down the docker compose with
Login as root with
sudo su -.
Open the docker's volume for bitcoind :
cd /var/lib/docker/volumes/generated_bitcoin_datadir/, and check its content with
ls -la. You should see only one directory named
Now remove the
rm -r _data. If for any reason you want to keep this directory and its content you can also rename it instead :
mv _data/ _data.old/
Now create a symbolic link between
/var/lib/docker/volumes/generated_bitcoin_datadir/_data and your data directory (
.bitcoin) on your host:
ln -s path/to/.bitcoin /var/lib/docker/volumes/generated_bitcoin_datadir/_data
Check that the link has been done with a
Start your docker-compose again with
Your BTCPay Server should now be fully synched.