Troubleshooting

This guide helps you resolve common issues when using LinQup. Most problems have simple solutions!

Wallet Connection Issues

Wallet Not Connected

Problem: "Wallet is not connected" message appears

Solutions:

1. Click the Connect Wallet button in the top right
2. Select your wallet (MetaMask, Coinbase Wallet, etc.)
3. Approve the connection in your wallet pop-up
4. Refresh the page if the connection doesn't appear

Wrong Network

Problem: "Switch to Polygon network" message

Solutions:

1. Automatic Switch - Click the button to auto-switch networks
2. Manual Switch in MetaMask:
   • Open MetaMask
   • Click the network dropdown (top center)
   • Select "Polygon Mainnet"
   • If not listed, add it manually (see Wallet Setup)

Transaction Rejected

Problem: Transaction cancelled or rejected

Cause: You clicked "Reject" in your wallet

Solution:

• Try the action again
• Click "Confirm" or "Approve" in your wallet when prompted
• Make sure you have enough MATIC for gas fees

Balance and Fund Issues

Insufficient USDC or USDCx

Problem: "Not enough USDC or USDCx" error

Required Balance: To start a stream, you need approximately:

• Monthly Amount × 3 + 4-hour deposit
• Example: For $100/month stream = ~$300.55 USDCx required

Solutions:

1. Get USDC - Purchase USDC on an exchange and send to your wallet
2. Auto-Conversion - LinQup automatically converts USDC to USDCx during stream creation
3. Check Balance - Verify you have enough USDC before starting

See Getting USDC for detailed instructions.

Insufficient Gas (MATIC)

Problem: "Insufficient ETH for transaction fees" error

Cause: Not enough MATIC to pay blockchain transaction fees

Solutions:

1. Get MATIC - Purchase MATIC on an exchange
2. Bridge - Use Polygon Bridge to move MATIC from Ethereum
3. Amount Needed - Usually $1-2 worth of MATIC is sufficient for multiple transactions

Token Approval and Conversion Errors

Approval Failed

Problem: "Failed to approve USDC spending" message

Common Causes:

• Wrong network selected
• Insufficient MATIC for gas
• Network connection issues

Solutions:

1. Verify you're on Polygon network (not Ethereum)
2. Check you have MATIC for gas fees
3. Wait a moment and try again
4. Clear your browser cache and reload

USDC to USDCx Conversion Failed

Problem: "Failed to convert USDC to USDCx" error

Solutions:

1. Wait and Retry - System automatically retries with 2-second delay
2. Check Network - Ensure you're on Polygon network
3. After Network Switch - Wait 5-10 seconds after switching networks, then retry
4. Verify Balance - Make sure you have enough USDC to convert

Approval Timeout (3 Minutes)

Problem: Wallet approval taking too long

What Happens:

• After 3 minutes waiting for approval, a timeout occurs
• "Click to open wallet" button appears

Solutions:

1. Click the "Click to open wallet" button
2. Find the pending transaction in your wallet
3. Approve or reject it
4. If stuck, cancel the transaction and start over

Network Errors

Connection Timeout

Problem: "Connection failed. Please check your internet connection" message

Solutions:

1. Check your internet connection
2. Wait a few seconds - system auto-retries with 3-5s delay
3. Refresh the page
4. Try a different RPC endpoint (advanced users)

Rate Limit Error

Problem: "Too many requests. Please wait before retrying"

Cause: Too many requests to blockchain RPC nodes

Solution:

• Wait 30 seconds
• System automatically retries
• Avoid rapid clicking of buttons

RPC Error

Problem: "Failed to communicate with blockchain" error

Solutions:

1. Wait - Temporary RPC issues usually resolve within minutes
2. Retry - System automatically retries with exponential backoff
3. Check Status - Visit Polygon Status for network status
4. Change RPC (Advanced) - Add a different Polygon RPC endpoint in MetaMask

Stream Creation Issues

Stream Creation Failed

Problem: Stream creation transaction fails

Troubleshooting Steps:

1. Check Wallet

   • Wallet connected?
   • Correct network (Polygon)?
   • Sufficient USDC/USDCx?
   • Enough MATIC for gas?

2. Retry Process

   • Start the stream creation again
   • Complete each step: Balance check → Approval → Conversion → Create

3. Check Transaction

   • Look for transaction hash
   • View on Polygonscan
   • Check if transaction failed or reverted

Transaction Pending Too Long

Problem: Transaction stuck in "pending" state

Solutions:

1. Wait - Polygon transactions usually complete in 2-10 seconds
2. Check Polygonscan - Verify transaction status
3. Speed Up (Advanced):
   • Open MetaMask
   • Go to Activity tab
   • Click transaction
   • Click "Speed Up" to increase gas price
4. Cancel and Retry - As last resort, cancel transaction and start over

NFT Minting Errors

NFT Mint Failed

Problem: "NFT minting failed" error

Common Causes:

• Insufficient MATIC for gas
• Network congestion
• Max supply reached

Solutions:

1. Retry - System offers automatic retry
2. Check Balance - Ensure enough MATIC
3. Check Max Supply - Verify template hasn't reached mint limit
4. Wait and Retry - Network congestion usually temporary

Max Supply Reached

Problem: "Maximum supply reached" error

Cause: The NFT template has hit its mint limit

Solution:

• Contact the creator - they need to create a new template or increase max supply
• As creator: Create new NFT template with higher or unlimited supply

Metadata Upload Failed

Problem: Metadata couldn't be uploaded to Irys/Arweave

Solutions:

1. Automatic Retry - System retries with 2s delay
2. Check USDC/POL - Irys storage requires small payment
3. Network Issues - Wait and retry if Irys service is slow

Dashboard Issues

Data Not Updating

Problem: Dashboard showing old data

Solutions:

1. Pull-to-Refresh (Mobile) - Swipe down on the page
2. Manual Refresh - Click browser refresh button
3. Wait - Real-time data updates at 60 FPS, but initial load may take a moment
4. Check Connection - Ensure wallet is still connected

Supporters Not Showing

Problem: Can't see supporters in the list

Checks:

1. Filters - Make sure "All" filter is selected, not just "Active" or "Inactive"
2. Wallet Connected - Verify you're connected with correct wallet
3. Wait for Sync - Initial data load may take a few seconds

Browser and Device Issues

MetaMask Not Appearing

Problem: Wallet connection pop-up doesn't show

Solutions:

1. Check Pop-up Blocker - Allow pop-ups for LinQup
2. Click MetaMask Extension - Manually open MetaMask
3. Refresh Page - Reload and try connecting again
4. Update MetaMask - Ensure latest version installed

Mobile Wallet Issues

Problem: Wallet not connecting on mobile

Solutions:

1. Use WalletConnect - Select WalletConnect option
2. In-App Browser - Open LinQup in your wallet's built-in browser
3. MetaMask Mobile - Use MetaMask app browser
4. Trust Wallet - Use Trust Wallet dApp browser

Page Won't Load

Problem: LinQup page not loading

Solutions:

1. Clear Cache - Clear browser cache and cookies
2. Try Incognito - Open in private/incognito window
3. Different Browser - Try Chrome, Firefox, or Brave
4. Disable Extensions - Temporarily disable browser extensions
5. Check Network - Visit vercel.com to verify hosting status

Error Messages Reference

Common Error Codes

Validation Errors

Ethereum Address Format

• Must be 42 characters
• Start with 0x
• Followed by 40 hex characters (0-9, a-f)

Transaction Hash Format

• Must be 66 characters
• Start with 0x
• Followed by 64 hex characters

Still Having Issues?

If you've tried these solutions and still need help:

1. Check Recent Updates

   • Visit LinQup status page (if available)
   • Check GitHub Issues for known issues

2. Gather Information

   • What were you trying to do?
   • What error message appeared?
   • Transaction hash (if available)
   • Browser and wallet used
   • Screenshots of the error

3. Get Support

   • Open a GitHub Issue
   • Include all gathered information above

Next Steps

• Learn about advanced streaming features
• Return to getting started guide
• View dashboard guide