Skip to main content
This guide covers common issues you might encounter while using Sable Protocol and how to resolve them.

​
Wallet Connection Issues

Symptoms: Wallet button shows “Connect Wallet” but nothing happens when clicked.Solutions:
  1. Install a compatible wallet:
  2. Ensure wallet extension is unlocked:
    • Click the wallet extension icon
    • Enter your password if prompted
  3. Check wallet network:
    • Open your wallet extension
    • Verify you’re connected to StarkNet Mainnet
    • Switch networks if needed
  4. Clear browser cache: 
    # Chrome/Brave: Ctrl+Shift+Delete
# Firefox: Ctrl+Shift+Delete
# Safari: Cmd+Option+E
  5. Try a different browser:
    • Argent X works best on Chrome/Brave
    • Braavos supports Chrome, Firefox, and Edge
Symptoms: Wallet is connected but shows $0.00 balance.Causes:
  • RPC endpoint is down or slow
  • Account has no WBTC balance
  • Price feed temporarily unavailable
Solutions:
  1. Wait 30 seconds - Balance data fetches on a polling interval
  2. Refresh the page - Force a new data fetch
  3. Check your actual balance:
    • Open wallet extension
    • Verify WBTC balance
    • If zero, you need to acquire WBTC first
  4. Verify RPC connection:
    • Open browser console (F12)
    • Look for RPC errors
    • If errors persist, try again in 5-10 minutes
Symptoms: Error message “Please connect to StarkNet Mainnet”Solution:
  1. Open your wallet extension
  2. Click the network dropdown (top right)
  3. Select StarkNet Mainnet
  4. Refresh the page
Sable only operates on Mainnet. Testnet deployments are not available.

​
Transaction Failures

Symptoms: Wallet popup appears but transaction fails or is rejected.Common causes:
  1. Insufficient gas funds:
    • StarkNet requires ETH for gas fees
    • Minimum: ~0.001 ETH for most transactions
    • Solution: Bridge or buy ETH on StarkNet
  2. User rejected transaction:
    • You clicked “Reject” or “Cancel”
    • Solution: Try again and approve the transaction
  3. Transaction timeout:
    • Wallet popup took too long to approve
    • Solution: Refresh page and try again faster
Symptoms: Transaction shows “Pending” for 5+ minutes.StarkNet confirmation times:
  • Normal: 10-60 seconds
  • High load: 2-5 minutes
  • Network issues: 10+ minutes
Solutions:
  1. Wait patiently - StarkNet blocks can take time
  2. Check transaction on Voyager:
    • Copy transaction hash
    • Visit voyager.online
    • Paste hash to see actual status
  3. If truly stuck (30+ min):
    • Refresh the page
    • Transaction will eventually confirm or fail
    • Do NOT submit duplicate transactions
Symptoms: Transaction confirmed but shows “Failed” status on Voyager.Common reasons:
  1. Insufficient token allowance:
    • You didn’t approve enough tokens
    • Solution: Check approval amount and approve more
  2. Slippage tolerance exceeded:
    • Price moved unfavorably during swap
    • Solution: Increase slippage tolerance (for DCA/swaps)
  3. Contract reverted:
    • Check error message on Voyager
    • Common: “Insufficient balance”, “Not enough liquidity”
  4. Health factor too low (CDP):
    • Trying to borrow too much
    • Solution: Reduce borrow amount or add more collateral

​
Insufficient Balance Errors

Symptoms: “Insufficient balance” when trying to deposit into vault.Solutions:
  1. Acquire WBTC on StarkNet:
    • Use the Bridge tab to bridge BTC from other chains
    • Buy WBTC on a StarkNet DEX (AVNU, Ekubo)
    • Transfer from a CEX that supports StarkNet
  2. Check minimum deposit:
    • Some vaults have minimum deposit amounts
    • Example: Sentinel vault minimum is 0.00001 BTC
Symptoms: “Insufficient balance for gas” error.Solution:You need ETH on StarkNet for gas fees:
  1. Bridge ETH to StarkNet:
  2. Buy ETH on StarkNet:
    • Use a CEX that supports StarkNet withdrawals
    • Recommended: OKX, Binance
  3. Minimum ETH needed:
    • Vault deposit: ~0.0005 ETH
    • DCA order: ~0.001 ETH
    • CDP operations: ~0.0008 ETH
Symptoms: “Insufficient liquidity” when trying to borrow.Causes:
  • Nostra lending pool has low USDC available
  • You’re trying to borrow at max LTV (70%)
Solutions:
  1. Borrow less USDC - Try 50-60% LTV instead of 70%
  2. Wait for liquidity - More USDC may become available later
  3. Add more collateral - Deposit more WBTC to increase borrowing power

​
Privacy / Shielded Vault Issues

Symptoms: Can’t find note to withdraw shielded deposit.CRITICAL: If you lose your privacy note, your funds are unrecoverable.Prevention:
  1. Backup notes immediately:
    • Notes are stored in browser localStorage
    • Export/copy note string after deposit
    • Save in password manager or secure location
  2. Check browser history:
    • Notes might be in a different browser
    • Try the browser/device you used for deposit
  3. Check localStorage:
    • Open browser console (F12)
    • Go to Application → Local Storage
    • Look for keys starting with shielded_notes_
We cannot recover lost notes. Always backup immediately after deposit.
Symptoms: “Failed to generate proof” error when withdrawing.Causes:
  • Browser ran out of memory (proof gen uses ~2GB RAM)
  • WASM worker failed to load
  • Browser doesn’t support WebAssembly
Solutions:
  1. Close other tabs - Free up browser memory
  2. Use a desktop browser:
    • Chrome/Brave (recommended)
    • Firefox
    • Safari works but slower
  3. Avoid mobile browsers:
    • Mobile devices may not have enough memory
    • Use desktop for privacy withdrawals
  4. Wait and retry:
    • Proof generation takes 30-90 seconds
    • Don’t refresh during proof generation
Symptoms: Proof generated but transaction fails with “Invalid proof”.Causes:
  • Note already withdrawn (double-spend attempt)
  • Wrong Merkle tree root (deposit not yet batched)
  • Note is from wrong pool
Solutions:
  1. Check note status:
    • Verify note hasn’t already been withdrawn
    • Check transaction history
  2. Wait for batch processing:
    • Deposits must be batched (3 deposits per batch)
    • If you’re in an incomplete batch, wait for 2 more deposits
  3. Verify pool address:
    • Ensure note is for the correct pool
    • Sentinel vs Delta Neutral vs Stablecoin

​
RPC and Network Errors

Symptoms: “Failed to fetch” or “Network error” messages.Causes:
  • Lava RPC endpoint is down
  • Rate limit exceeded
  • Network congestion
Solutions:
  1. Wait 1-2 minutes - Temporary outage
  2. Refresh the page - Force new RPC connection
  3. Use different RPC (advanced): 
    # .env.local
NEXT_PUBLIC_STARKNET_RPC=https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_8/YOUR_KEY
  4. Check StarkNet status:
Symptoms: “Contract not found” or “Execution error”.Solutions:
  1. Verify contract address:
  2. Clear cache and refresh:
    • Browser might have stale contract state
  3. Check contract on Voyager:
    • Visit voyager.online
    • Paste contract address
    • Verify contract is deployed and not paused

​
DCA Issues

Symptoms: Order created but no executions happening.Causes:
  • Keeper bot hasn’t run yet (runs every 6 hours)
  • Next execution time not reached
  • AVNU liquidity unavailable
Solutions:
  1. Check next execution time:
    • View order details
    • Wait until scheduled time
  2. Verify order is active:
    • Not cancelled
    • Has remaining orders
    • Has sufficient deposited funds
  3. Be patient:
    • Keeper bot runs on a schedule
    • Orders execute within 6 hours of due time
Symptoms: Deposited more than expected for Smart DCA orders.This is expected behavior:Smart DCA adjusts buy amounts based on Mayer Multiple:
  • When BTC is cheap (MM < 0.8): Buy 1.5x more
  • When expensive (MM > 2.0): Buy 0.5x less
The 1.5x deposit buffer covers worst-case:
  • If ALL orders execute at 1.5x (max), you have enough
  • Unused funds are automatically refunded when order completes
Example:
10 USDC × 4 orders × 1.5 buffer = 60 USDC deposited
Actual spent: 45 USDC
Refunded: 15 USDC

​
CDP Issues

Symptoms: Can’t borrow more, “Health factor below minimum”.Solution:Your health factor must stay above 1.0 to avoid liquidation:
  1. Add more collateral:
    • Deposit more WBTC
    • Increases health factor
  2. Repay some debt:
    • Repay USDC loan
    • Decreases debt, improves health factor
  3. Wait for BTC price to rise:
    • Collateral value increases
    • Health factor improves automatically
Health Factor ranges:
  • 2.0+: Very Safe (green)
  • 1.5-2.0: Safe (green)
  • 1.0-1.5: Caution (yellow)
  • < 1.0: Liquidation Risk (red)
Symptoms: “Close Position” button disabled or fails.Requirements to close:
  1. Must have enough USDC:
    • Need to repay full debt + accrued interest
    • Check “Total Debt” amount
  2. Approve USDC first:
    • Click “Approve USDC” if needed
    • Wait for approval transaction to confirm
  3. Sufficient ETH for gas:
    • Closing requires 2 transactions
    • Need ~0.001 ETH total

​
Performance Issues

Causes:
  • RPC endpoint slow
  • Fetching data from multiple external APIs
  • Poor internet connection
Solutions:
  1. Check internet connection
  2. Try different RPC endpoint (see RPC errors section)
  3. Hard refresh:
    • Windows/Linux: Ctrl + Shift + R
    • Mac: Cmd + Shift + R
  4. Clear browser cache
Symptoms: Performance charts show “No data available”.Causes:
  • DefiLlama API rate limit
  • No historical data yet (new vault)
Solutions:
  1. Wait 30 seconds - Data fetches on interval
  2. Refresh page - Retry API call
  3. New vaults - May not have historical data yet

​
Still Need Help?

If you’re still experiencing issues:

Join Discord

Get support from the community

Open GitHub Issue

Report bugs or request features

Check Status

View StarkNet network status

View Documentation

Review full documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us