Why adjust BitBoxApp gap limits?
If your BitBoxApp isn't showing your coin balance correctly, especially after transactions made outside the app (like UTXO consolidation), adjusting the gap limits for receive and/or change addresses can often fix it. This guide shows you how to do this on macOS, Linux (package installations and AppImage), and Windows.
Important: Before you start, make sure the BitBoxApp is completely closed.
How to adjust gap limits
You'll use command-line instructions specific to your operating system. In the examples below, we use a value of 50. You can change this to your preferred limit (often, a value around 20 is enough, but you might need more if you've made many transactions without opening the app or used addresses further ahead in your wallet).
Adjust gap limits on macOS
To launch the BitBoxApp with custom gap limits, open your terminal and enter one of the following commands:
- To set the receive address gap limit (e.g., to 50):
open -a BitBoxApp --args -gapLimitReceive 50- To set the change address gap limit (e.g., to 50):
open -a BitBoxApp --args -gapLimitChange 50- To set both limits simultaneously (e.g., to 50):
open -a BitBoxApp --args -gapLimitReceive 50 -gapLimitChange 50Adjust gap limits on Linux
The command depends on how you installed the BitBoxApp.
1. Package installations (e.g., .deb, .rpm)
If you installed BitBoxApp via a package manager, the command-line tool is usually BitBox and available in your system's PATH.
- To set the receive address gap limit:
BitBox -gapLimitReceive 50- To set the change address gap limit:
BitBox -gapLimitChange 50- To set both limits:
BitBox -gapLimitReceive 50 -gapLimitChange 50If the BitBox command doesn't work, find its full path using which BitBox or whereis BitBox. It's often in /usr/bin or /usr/local/bin. For example, on Ubuntu/Debian:
$ which BitBox
/usr/bin/BitBox
$ /usr/bin/BitBox -gapLimitReceive 502. AppImage
If you're using an AppImage:
- First, make the AppImage file executable (if you haven't already):
chmod +x BitBox-[version]-x86_64.AppImage(Replace BitBox-[version]-x86_64.AppImage with your actual file name)
- To set the receive address gap limit:
./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50- To set the change address gap limit:
./BitBox-[version]-x86_64.AppImage -gapLimitChange 50- To set both limits:
./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50 -gapLimitChange 50Adjust gap limits on Windows
On Windows, you'll use BitBox.exe. It's usually in the installation folder (e.g., C:\Program Files\BitBox or C:\Users\YOUR_USERNAME\AppData\Local\Programs\BitBox).
- Open Command Prompt or PowerShell.
- Navigate to the BitBoxApp installation directory. For example:
cd "C:\Program Files\BitBox"- Then, run one of the following commands:
- To set the receive address gap limit:
.\BitBox.exe -gapLimitReceive 50- To set the change address gap limit:
.\BitBox.exe -gapLimitChange 50- To set both limits:
.\BitBox.exe -gapLimitReceive 50 -gapLimitChange 50Once you run the appropriate command, the BitBoxApp will launch with the updated gap limits, and your balances should display correctly.