Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/satsigner/satsigner/llms.txt

Use this file to discover all available pages before exploring further.

This guide helps you resolve common issues when using SatSigner. If you don’t find a solution here, please check the FAQ or open an issue on GitHub.

​
Installation Issues

​
App won’t install on iOS

Problem: Cannot install SatSigner from the App Store on iPhone or iPad. Solutions:
  1. Check iOS version: SatSigner requires iOS 14.0 or later
    • Go to Settings → General → About → Check Software Version
    • Update iOS if needed: Settings → General → Software Update
  2. Check storage space: Insufficient space can prevent installation
    • Go to Settings → General → iPhone Storage
    • Free up at least 500 MB of space
  3. Restart device: Force restart your iPhone/iPad
    • iPhone 8 or later: Press volume up, volume down, then hold power button
    • Older models: Hold home + power buttons
  4. Sign out and back into App Store
    • Settings → [Your Name] → Media & Purchases → Sign Out
    • Sign back in and try again

​
App won’t install on Android

Problem: Cannot install SatSigner from Google Play Store. Solutions:
  1. Check Android version: SatSigner requires Android 10.0 or later
    • Go to Settings → About Phone → Check Android Version
    • Update if available
  2. Clear Google Play Store cache
    • Settings → Apps → Google Play Store
    • Tap Storage → Clear Cache and Clear Data
    • Restart Play Store and try again
  3. Check device compatibility: Some devices may have restrictions
    • Ensure your device passes SafetyNet (if required)
    • Check if your device is rooted (may cause issues)
  4. Enable installation from unknown sources (for APK installs)
    • Settings → Security → Enable Unknown Sources
    • Only use official APKs from GitHub releases
Only download SatSigner from official sources: App Store, Google Play, or official GitHub releases. Never install APKs from untrusted sources.

​
App crashes on launch

Problem: SatSigner opens then immediately closes. Solutions:
  1. Force quit and restart
    • iOS: Swipe up from bottom, swipe app away, reopen
    • Android: Settings → Apps → SatSigner → Force Stop, then reopen
  2. Clear app cache (Android)
    • Settings → Apps → SatSigner → Storage → Clear Cache
    • Note: Does not delete wallet data
  3. Reinstall the app
    • First: Ensure you have backups of all wallet recovery information!
    • Uninstall SatSigner
    • Restart device
    • Reinstall from App Store/Play Store
    • Restore wallets from backup
  4. Check for updates: Update to the latest version
  5. Report the crash: Open a GitHub issue with:
    • Device model and OS version
    • SatSigner version
    • What you were doing when it crashed

​
Wallet Creation Issues

​
Cannot create new wallet

Problem: Wallet creation fails or gets stuck. Solutions:
  1. Check network connection
    • Ensure you have internet connectivity
    • Try switching between WiFi and mobile data
    • Some wallet types can be created offline
  2. Verify PIN setup
    • Make sure you completed PIN setup
    • Try creating a new PIN in Settings
  3. Check available storage
    • Ensure device has sufficient free space
    • At least 100 MB recommended
  4. Try different wallet type
    • If multi-sig fails, try single-sig first
    • Use testnet to test wallet creation

​
Mnemonic seed phrase not generated

Problem: No seed phrase displayed during wallet creation. Solutions:
  1. Check entropy source: SatSigner uses device’s secure random generator
    • Restart device and try again
    • Ensure app has necessary permissions
  2. Import existing seed: If creating new wallet fails, try importing a seed generated elsewhere
    • Use a trusted source like hardware wallet
    • Verify checksum
  3. Check for updates: Older versions may have bugs
Never use a seed phrase from an untrusted source. Always generate seeds using trusted hardware or software.

​
Invalid descriptor error

Problem: “Invalid descriptor” error when importing wallet. Solutions:
  1. Verify descriptor format
    • Check for typos or missing characters
    • Ensure checksum is included
    • Descriptors are case-sensitive
  2. Check descriptor type compatibility
    • SatSigner supports: pkh(), wpkh(), sh(wpkh()), tr(), wsh(), sh(wsh()), sh()
    • Verify script type is supported
  3. Validate checksum
    • Descriptor checksums start with #
    • Recalculate checksum if unsure
    • Some tools export descriptors without checksums
  4. Try without checksum first, then add it: 
    wpkh([d34db33f/84h/0h/0h]xpub6ERa...RggN6/0/*)#checksum
See Wallet Management for descriptor examples.

​
Transaction Issues

​
Transaction won’t send

Problem: Cannot broadcast transaction to network. Solutions:
  1. Check network connection
    • Verify internet connectivity
    • Try switching networks (WiFi ↔ mobile data)
    • Check if backend server is reachable
  2. Verify transaction details
    • Ensure recipient address is valid
    • Check amount doesn’t exceed balance
    • Verify fee rate is reasonable (>1 sat/vByte)
  3. Check UTXO availability
    • Ensure selected UTXOs are confirmed
    • Unconfirmed UTXOs may not be spendable
    • Try selecting different UTXOs
  4. Validate signature
    • For multisig: Ensure enough signatures collected
    • Check that correct keys are being used
    • Verify fingerprints match
  5. Check mempool limits
    • If fee rate is too low (less than 1 sat/vByte), node may reject
    • Increase fee rate and try again

​
Transaction stuck (unconfirmed)

Problem: Transaction broadcast but not confirming. Solutions:
  1. Check mempool position
    • Use SatSigner’s blockchain explorer
    • View your transaction’s fee rate vs. current rates
    • Low-fee transactions may wait days or weeks
  2. Wait it out
    • If fee rate is reasonable, just wait
    • Blocks are mined every ~10 minutes on average
    • Congestion can cause delays
  3. Use RBF (Replace-By-Fee)
    • If you enabled RBF when creating the transaction:
      1. Open the pending transaction
      2. Tap Bump Fee
      3. Set higher fee rate
      4. Broadcast replacement transaction
    • New transaction replaces old one in mempool
  4. Use CPFP (Child-Pays-For-Parent)
    • If RBF not enabled:
      1. Spend the unconfirmed change output
      2. Use a very high fee rate
      3. Miners will process both transactions together
  5. Transaction may drop from mempool
    • After ~2 weeks, unconfirmed transactions drop
    • Funds return to your wallet (no double-spend risk)
    • You can try sending again with higher fee
Always enable RBF when creating transactions. This allows you to increase fees later if needed.

​
”Insufficient funds” error

Problem: Error says insufficient funds despite having balance. Solutions:
  1. Account for transaction fees
    • Total cost = Amount + Fee
    • If sending entire balance, reduce amount to leave room for fee
    • Use “Send Max” button to automatically calculate
  2. Check UTXO availability
    • Some UTXOs may be unconfirmed
    • Some may be locked or marked as “do not spend”
    • Go to UTXO view and check available coins
  3. Verify selected UTXOs
    • If manually selecting coins, ensure enough selected
    • Try auto-selection instead
  4. Check for dust limits
    • Very small UTXOs (less than 546 sats) may not be spendable
    • Consolidate dust when fees are low

​
Wrong fee calculated

Problem: Fee seems too high or too low. Solutions:
  1. Understand fee calculation
    • Fee = Transaction Size (vBytes) × Fee Rate (sat/vByte)
    • More inputs (UTXOs) = larger transaction = higher fee
    • SegWit transactions are smaller than legacy
  2. Check fee rate source
    • SatSigner fetches real-time rates from mempool
    • Rates change based on network congestion
    • You can set custom rate in advanced settings
  3. Reduce transaction size
    • Use fewer inputs (select larger UTXOs)
    • Use fewer outputs (consolidate recipients)
    • Use SegWit addresses (wpkh/tr)
  4. Use custom fee rate
    • Tap “Custom” in fee selector
    • Enter desired sat/vByte rate
    • View current mempool rates for reference
See Transaction Building for fee optimization tips.

​
Multi-signature Issues

​
Cannot create multisig wallet

Problem: Multi-signature wallet creation fails. Solutions:
  1. Verify cosigner information
    • Need M-of-N cosigner xpubs
    • All xpubs must be same derivation path
    • Fingerprints must be unique
  2. Check descriptor format
    • Multisig uses sortedmulti() or wsh(multi())
    • Verify ordering (SatSigner uses sortedmulti)
    • Ensure all xpubs are valid
  3. Coordinate with cosigners
    • All cosigners need same wallet configuration
    • Share descriptors securely
    • Verify fingerprints match

​
PSBT signature missing

Problem: Cannot sign or combine PSBT. Solutions:
  1. Verify you have signing keys
    • PSBTs require private keys to sign
    • Watch-only wallets cannot sign
    • Check fingerprint matches your key
  2. Check PSBT format
    • Ensure PSBT is valid and properly encoded
    • Try re-importing PSBT
    • Check for corruption during transfer
  3. Verify threshold not met
    • For 2-of-3, need 2 signatures
    • Check how many signatures already present
    • Each cosigner must sign separately
  4. Check derivation paths
    • PSBT derivation must match wallet
    • Verify BIP32 paths are correct
See Multi-signature Wallets for detailed setup.

​
Connection Issues

​
Cannot connect to backend server

Problem: “Connection failed” or “Cannot reach server” errors. Solutions:
  1. Check internet connection
    • Verify WiFi or mobile data is working
    • Try opening a web page to confirm
    • Restart router if needed
  2. Verify backend settings
    • Go to Settings → Network
    • Check Electrum or Esplora server URL
    • Try default servers or alternative servers
  3. Test different server
    • Add custom Electrum server:
      • blockstream.info:50002 (Blockstream)
      • electrum.blockstream.info:50002
    • Or add custom Esplora URL:
      • https://blockstream.info/api
  4. Check firewall/VPN
    • Corporate networks may block Bitcoin traffic
    • Try disabling VPN temporarily
    • Use mobile data to test
  5. Use Tor (advanced)
    • Enable Tor in Settings for censorship resistance
    • Requires Tor installation (Orbot on Android)

​
Sync takes too long

Problem: Wallet sync is very slow or stuck. Solutions:
  1. Check connection speed
    • Slow internet = slow sync
    • Wait for completion (may take several minutes)
    • Try faster network
  2. Try different backend
    • Switch between Electrum and Esplora
    • Some servers are faster than others
    • Use geographically closer server
  3. Check gap limit
    • Large gap limits take longer to sync
    • Default is 20 (usually sufficient)
    • Only increase if you know you need it
  4. Restart sync
    • Pull down to refresh
    • Force quit app and reopen
    • Last resort: delete and re-import wallet

​
Lightning & Advanced Features

​
Cannot connect to LND node

Problem: Lightning node connection fails. Solutions:
  1. Verify LND REST API enabled
    • Check lnd.conf has REST listener enabled
    • Default port: 8080
    • Ensure firewall allows connection
  2. Check connection details
    • Host: IP address or domain
    • Port: Usually 8080
    • TLS certificate: Must be valid
    • Macaroon: Needs proper permissions
  3. Test from browser
    • Try accessing https://your-node:8080/v1/getinfo
    • Should return JSON response
    • If this fails, problem is with node, not SatSigner
  4. Check certificate
    • LND uses self-signed certs by default
    • May need to import cert into device
    • Or use Let’s Encrypt cert on node
See Lightning Integration for setup details.

​
eCash tokens not received

Problem: eCash tokens not appearing in wallet. Solutions:
  1. Verify mint connection
    • Check mint URL is correct
    • Mint must be online and responsive
    • Try pinging mint from browser
  2. Check token format
    • Cashu tokens start with cashuA...
    • Ensure entire token was copied
    • Tokens are case-sensitive
  3. Verify mint is added
    • Go to eCash → Mints
    • Ensure the mint is in your list
    • Add mint if missing
  4. Check mint balance
    • Mint may be out of reserves
    • Try different mint
    • Verify mint reputation
eCash is custodial. Only use trusted mints and don’t store large amounts.

​
Nostr sync not working

Problem: Labels not syncing across devices. Solutions:
  1. Verify Nostr settings
    • Ensure sync is enabled on all devices
    • Same Nostr keypair on all devices
    • At least one relay configured
  2. Check relay connection
    • Go to Settings → Nostr → Relays
    • Verify relays are online (green indicator)
    • Add more relays for redundancy:
      • wss://relay.damus.io
      • wss://relay.nostr.band
      • wss://nos.lol
  3. Force re-sync
    • Pull down to refresh in Labels view
    • Or disable/re-enable sync
  4. Check encryption
    • Labels are encrypted with device keys
    • Ensure trusted devices are added
    • Remove and re-add device if needed
See Nostr Sync for troubleshooting steps.

​
Data & Recovery

​
Lost seed phrase

Problem: Cannot find mnemonic seed backup. Solutions: Unfortunately, if you lost your seed phrase and:
  • Your device is lost/broken
  • You don’t have other backups (descriptor, xprv)
  • You cannot access the app with your PIN
Your funds are not recoverable. This is why Bitcoin security is critical. Prevention:
  1. Write seed phrase on paper during wallet creation
  2. Store in multiple secure physical locations
  3. Consider metal backups for durability
  4. Never store digitally (photos, files, cloud)
  5. Export descriptors as additional backup
See Backup & Recovery for best practices.

​
Forgot PIN

Problem: Cannot remember PIN to unlock SatSigner. Solutions:
  1. Try all possible PINs
    • If you remember partial PIN, try variations
    • SatSigner may have attempt limits
  2. Use duress PIN
    • If you set one up, it opens alternative wallet
    • May have different funds or be empty
  3. Restore from backup
    • Uninstall and reinstall SatSigner
    • Import wallets using seed phrase or xprv
    • Create new PIN
    • Will lose labels unless you have BIP329 export
  4. No way to reset PIN without reinstalling
    • This is by design for security
    • PIN protects encryption key
    • No PIN = no access to encrypted data

​
App data corrupted

Problem: App data seems corrupted or inconsistent. Solutions:
  1. Backup current state (if possible)
    • Export descriptors
    • Export labels (BIP329)
    • Screenshot wallet settings
  2. Clear cache (Android)
    • Does not delete wallet data
    • May resolve UI issues
  3. Reinstall app
    • Back up recovery info first!
    • Uninstall completely
    • Reinstall fresh
    • Import wallets from backup
  4. Report the issue
    • Open GitHub issue with details
    • Include steps to reproduce
    • Help improve SatSigner

​
Performance Issues

​
App is slow or laggy

Problem: SatSigner performance is poor. Solutions:
  1. Check device resources
    • Close other apps
    • Restart device
    • Ensure sufficient free RAM
  2. Reduce visual effects
    • Disable animations in Settings (if available)
    • Use simpler UTXO visualizations
  3. Limit loaded wallets
    • Too many active wallets can slow down sync
    • Archive unused wallets
  4. Update app and OS
    • Newer versions may have performance improvements
    • OS updates can improve app performance

​
High battery usage

Problem: SatSigner draining battery quickly. Solutions:
  1. Reduce sync frequency
    • Disable auto-sync if not needed
    • Sync manually when needed
  2. Disable background refresh
    • iOS: Settings → SatSigner → Background App Refresh → Off
    • Android: Settings → Apps → SatSigner → Battery → Restrict
  3. Check for stuck processes
    • Force quit and reopen app
    • Restart device
  4. Update to latest version
    • May include battery optimizations

​
Still Need Help?

If you’ve tried these solutions and still have issues:

Check the FAQ

Common questions about SatSigner and Bitcoin

Read the Glossary

Understand Bitcoin terminology

GitHub Issues

Report bugs or request features

Documentation

Browse full documentation
When asking for help, never share your seed phrase, private keys, or PIN. No legitimate support person will ever ask for this information.