Question 1

How to fix BTCPay Keypad POS +/− buttons becoming unresponsive after the first tap on iOS Safari?

Accepted Answer

This affects the Keypad/Light POS view in BTCPay Server 2.3.9 and earlier. When `addToCart()` runs, `common.js` adds `posItem--added` to the item row, and `common.css` applies `.posItem--added { pointer-events: none }`. The class is normally removed after a `transitionend` event from the `.posItem-added` overlay. `VueLight.cshtml` is missing that overlay, so on iOS Safari the event never fires and the buttons remain blocked. Android works only because an unrelated Bootstrap button transition accidentally triggers `transitionend`.

Temporary workaround: close and reopen the Keypad items panel; this resets the row state.

Permanent code fix: in `VueLight.cshtml`, add the same `.posItem-added` overlay markup inside each Keypad item row that exists in `Cart.cshtml`, then rebuild and redeploy BTCPay. A more robust alternative is to avoid relying solely on `transitionend` in `common.js` and add a timeout fallback matching the CSS fade duration, for example:

```js
row.classList.add('posItem--added');
setTimeout(() => row.classList.remove('posItem--added'), 300);
```

As an emergency CSS-only workaround, you can force pointer events back on, but test the visual added-state behavior first:

```css
.posItem--added {
  pointer-events: auto !important;
}
```

Do not edit files directly inside a transient Docker container unless you commit them to a custom image; otherwise the change is lost when the container is recreated.

Question 2

Why does BTCPay show "The calculated rate should not be 0" and disable payment methods?

Accepted Answer

This happens when the primary exchange rate provider returns a zero or negative rate (e.g., yadio returns BTC_USD = 0). A temporary workaround is to switch to a different primary rate provider that does not return zero rates. Track issue #7376 for a permanent fix that will treat non-positive rates as invalid and allow fallback providers to run.

Question 3

Why does BTCPay Server show 'Your nodes are syncing' and not display Bitcoin blocks?

Accepted Answer

This indicates your underlying Bitcoin node (e.g., bitcoind) is still syncing the blockchain. Check sync status: for Docker deployments, run `docker logs bitcoind`; for Umbrel, check the Bitcoin Node app in the dashboard. Wait until fully synced. If stuck, restart the node service: `docker restart bitcoind` or reboot the Umbrel device. Ensure disk space and network connectivity are adequate. Once sync completes, the message disappears and wallet functions resume.

Question 4

Why are xUnit tests tagged with the FastTest trait not running in the BTCPayServer CI pipeline?

Accepted Answer

BTCPayServer CI workflows only select tests matching specific trait filters (`Fast=Fast|ThirdParty=ThirdParty` in ci.yml, plus `Playwright` and `Integration` jobs; `PreReleaseCheck=PreReleaseCheck` in release.yml). Tests marked only with `[Trait("FastTest", "FastTest")]` match none of these filters, so they are silently excluded from every CI job even though they pass locally. Fix: retag the affected tests with `[Trait("Fast", "Fast")]` so the existing fast-test job picks them up (this requires no CI changes since these tests need no external server or Docker services). Verify selection by building BTCPayServer.Tests and running `dotnet test --list-tests --filter "Fast=Fast|ThirdParty=ThirdParty"` (the same filtering mechanism used by docker-entrypoint.sh); the test should now appear. To run such tests directly before fixing, use `--filter "FastTest=FastTest"`. Note: tests are unaffected if their class carries another selected trait (e.g., `Integration`) via inheritance.

Question 5

How to fix BTCPay Lightning refund payout stuck in 'Awaiting Payment' with 'LNURL payRequest returned an invoice but its amount or hash did not match the request' error?

Accepted Answer

Cause: BTCPay Server v2.4.3+ (commit af8b6e5c) changed Lightning payout rounding to millisatoshi precision, so fiat-denominated refunds can produce fractional-satoshi payouts (e.g. 14729.443 sats). Some LNURL providers like Strike round the requested amount to a whole satoshi when generating the BOLT11 invoice, and BTCPay's strict exact-amount validation rejects it. The automated Lightning payout processor retries until its error threshold, then leaves the payout stuck in 'Awaiting Payment'. Workarounds: (1) Downgrade to v2.4.2 or earlier, which rounds LNURL payouts to whole satoshis. (2) Have the refund claimant provide a BOLT11 invoice (direct Lightning payout) instead of a Lightning Address/LNURL, since direct payouts keep millisatoshi precision. (3) Approve the refund using a conversion rate that yields a whole-satoshi BTC amount. (4) Process the stuck payout manually, as the automated processor disables itself after repeated failures.

BTCPay Server

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects