Skip to main content

Troubleshooting

Common issues and their solutions when using the SatsTerminal Borrow SDK.

Setup Issues

”apiKey is required”

Problem: SDK initialization fails with configuration error. Solution:
Check:
  • Environment variable is set
  • Variable name is correct
  • Value is not empty string

”wallet.signMessage must be a function”

Problem: Wallet provider configuration error. Solution:

“Setup failed” / Smart Account Error

Problem: setup() fails with SmartAccountError. Causes:
  1. Invalid signature from wallet
  2. Network connectivity issues
  3. API key issues
Solution:

Wallet Issues

”User rejected signature”

Problem: User cancelled the signature request. Solution:

“Invalid signature format”

Problem: Wallet returns signature in unexpected format. Solution:

Quote Issues

”No quotes available”

Problem: getQuotes() returns empty array or throws QuoteError. Causes:
  1. Collateral amount too small
  2. Loan amount too large for collateral
  3. LTV too high
  4. No liquidity available
Solution:

Workflow Issues

”Deposit not received” / Stuck on AWAITING_DEPOSIT

Problem: Workflow stuck waiting for deposit. Causes:
  1. BTC not sent to deposit address
  2. Transaction not confirmed
  3. Wrong amount sent
Solution:
  1. Verify transaction was sent to correct address
  2. Check transaction confirmations (typically need 1-3)
  3. Verify amount matches exactly

”Workflow timeout”

Problem: Workflow times out without completing. Solution:

“Bridge failed”

Problem: Collateral withdrawal bridge operation fails. Causes:
  1. Network congestion
  2. Bridge liquidity issues
  3. Invalid BTC address
Solution:

Session Issues

”Session expired”

Problem: Operations fail after session expires. Solution:

“Not initialized”

Problem: Account/session preload operations fail because account state is not initialized. Solution:

API Issues

”Rate limited” (429)

Problem: Too many API requests. Solution:

Storage Issues

”Storage quota exceeded”

Problem: Browser localStorage full. Solution:

React-Specific Issues

”Cannot update unmounted component”

Problem: State updates after component unmounts. Solution:

Debug Mode

Enable detailed logging:

Getting Help

If issues persist:
  1. Check documentation - docs.satsterminal.com
  2. Search issues - github.com/satsterminal/sdk/issues
  3. Contact support - support@satsterminal.com
When reporting issues, include:
  • SDK version
  • Error message and stack trace
  • Steps to reproduce
  • Browser/Node.js version
  • Relevant configuration (without API keys)