Common problems and what to try. If something here does not resolve your issue, see Reporting an Issue at the bottom of this page.
First, check that the browser has been granted camera access. Most browsers display a camera icon in the address bar when permission has been denied — click it and allow access, then reload the page.
If the camera opens but scanning fails: clean the lens with a soft cloth, improve lighting (aim for even illumination with no direct glare on the ColdCard Q screen), and try adjusting distance — typically 20–40 cm works well. Holding the camera at an angle to the screen can cause reflections; try facing it straight on.
If scanning is unreliable after these adjustments, the camera may not have sufficient resolution for BBQr. Webcams built into older laptops often struggle. The alternative is MicroSD transfer: download the file from the Keylay session to a computer, copy it to MicroSD, and load it directly on the ColdCard Q.
BBQr animated sequences consist of multiple frames; all frames must be captured for the transfer to complete. A progress indicator shows how many frames have been received. If progress stalls:
If the sequence consistently fails to complete, switch to MicroSD transfer.
Verify the session code was entered exactly as shared — codes are case-sensitive. Session codes expire after a period of inactivity; if the initiator created the session significantly earlier, create a new one and share the new code.
Keylay uses a WebSocket connection to the relay. Some corporate or institutional networks block WebSocket connections, and some VPNs do as well. If connecting from a restricted network, try a different network or disable the VPN temporarily.
If one participant connects but the other cannot, verify both are using the same code and that neither has a network restriction on their side specifically.
If the session drops, both participants should reload the Keylay page. The initiator creates a new session and shares a new code. Files already transferred do not need to be re-sent — each participant retains what they received before the drop. Resume from whichever step was interrupted.
Sparrow expects PSBTs saved as binary files (.psbt). If the file was saved or exported as base64 text, Sparrow may reject it. In Sparrow, use File → Save Transaction → As Binary when exporting; when importing, use File → Open Transaction → From File and select the binary .psbt file.
If Sparrow reports the PSBT as invalid after a round trip through a signer, check that the signer wallet and the Sparrow wallet are using the same script type (P2WSH for native SegWit multisig). A mismatch at setup will cause every PSBT to fail. This is a wallet configuration issue and requires rebuilding the wallet with consistent settings across all participants.
Confirm the file is in BSMS format (.bsms or .txt with BSMS content) and was exported from Sparrow using Settings → Export Wallet → BSMS. Other export formats are not compatible with the ColdCard Q's BSMS import path.
When importing via QR, use Multisig Wallets → Import from QR on the ColdCard Q and scan the QR displayed in Keylay. When importing via MicroSD, use Multisig Wallets → BSMS (BIP-129) and select the file.
If the ColdCard Q shows an XFP mismatch when registering the wallet, the descriptor contains an xpub from a different device or derivation path than the ColdCard Q expects. This indicates the wrong export was used during setup. Identify which signer's xpub is incorrect, re-export from the correct device using Advanced / Tools → Export Wallet → Generic JSON, and rebuild the wallet in Sparrow with the corrected xpub.
If the ColdCard Q displays a different recipient address than what Sparrow shows, do not sign. This is a serious discrepancy. It can indicate a compromised coordinator machine substituting a malicious address, or a configuration mismatch between the wallet instances.
To investigate: verify that both Sparrow and the ColdCard Q are using the same wallet descriptor. If the descriptors match and the discrepancy persists, treat the coordinator machine as potentially compromised and do not proceed with that transaction until the cause is understood.
For a 2-of-3 wallet, two valid signatures are required. If broadcast fails, open the PSBT in Sparrow and check how many signatures it contains — Sparrow displays this in the transaction view. If only one signature is present, the second signer's PSBT has not been collected or combined yet.
If both signatures appear to be present but broadcast still fails, the two PSBTs may not have been combined correctly. In Sparrow, use Combine Transaction to merge two independently signed PSBTs before broadcasting. Loading each signed PSBT separately without combining is a common source of this error.
Keylay is tested on Android and iOS. Camera access on iOS requires Safari — third-party browsers on iOS use the same rendering engine but camera API behavior can vary. If the camera is not responding on iOS, try Safari specifically.
On Android, Chrome is the most reliably tested browser. If camera permission was previously denied, reset it in the browser's site settings for app.keylay.org.
File download and upload on mobile can behave differently than on desktop — if a file transfer appears to succeed but the file cannot be found, check the browser's download folder or the Files app.
If the steps above do not resolve your issue, or if you have found a bug, there are three ways to report it:
For reproducible bugs or unexpected behavior, open an issue on the keylaybtc GitHub. Include the browser and OS, a description of the steps that led to the issue, and what you expected versus what happened. Screenshots or screen recordings are helpful.
For issues you prefer not to discuss publicly — including anything related to security or operational concerns — contact contact@keylay.org directly.
For general questions or discussion, Keylay is also reachable on Nostr and X.
