Troubleshooting

Detailed solutions for common issues encountered while using FarFISH.

Wallet Connection Issues

"Connect Wallet" Button Not Working

Symptoms: Clicking "Connect Wallet" does nothing or shows no wallet options.

Solutions:

1. Check Wallet Extension Installed

   • MetaMask: Visit https://metamask.io/download/
   • Coinbase Wallet: Visit https://www.coinbase.com/wallet
   • Ensure extension icon visible in browser toolbar

2. Unlock Wallet

   • Open wallet extension
   • Enter password to unlock
   • Try connecting again

3. Refresh Page

   • Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
   • Clear browser cache if needed

4. Try Different Browser

   • Chrome: Best compatibility
   • Firefox: Good support
   • Brave: Built-in wallet may conflict (disable and use external wallet)
   • Safari: Limited wallet support

5. Disable Conflicting Extensions

   • Multiple wallet extensions can conflict
   • Disable all except one (e.g., keep MetaMask, disable Phantom, Trust Wallet)

6. Check Console for Errors

   • Press F12 to open DevTools
   • Go to "Console" tab
   • Look for red error messages
   • Share errors with support if unresolved

WalletConnect QR Code Not Appearing

Symptoms: Selecting "WalletConnect" shows blank modal or spinning loader.

Solutions:

1. Check Network Connection

   • Ensure stable internet
   • Try different WiFi/cellular network

2. Disable Ad Blockers

   • Ad blockers may block WalletConnect CDN
   • Whitelist app.farfish.xyz

3. Try Injected Connection Instead

   • If mobile wallet has browser, use "Injected" option
   • MetaMask mobile: Use in-app browser (metamask:// links)

4. Clear WalletConnect Cache

   • Close wallet app completely
   • Reopen and try scanning again

5. Update Wallet App

   • Ensure latest version installed
   • Check App Store (iOS) or device settings (Android)

Wallet Shows Wrong Network

Symptoms: Wallet connected but shows Ethereum mainnet instead of Base.

Solutions:

MetaMask:

1. Click network dropdown (top left)
2. Select "Base Mainnet"
3. If not listed, click "Add Network"
4. Select "Base Mainnet" from list (or enter manually):
   • Network Name: Base Mainnet
   • RPC URL: https://mainnet.base.org
   • Chain ID: 8453
   • Currency Symbol: ETH
   • Block Explorer: https://basescan.org

Coinbase Wallet:

1. Tap/click network name (top center)
2. Select "Base"
3. Retry connection

After Switching:

• Refresh FarFISH page
• Wallet should now show Base network

Transaction Failures

Transaction Pending Forever

Symptoms: Transaction shows "Pending..." for 5+ minutes.

Diagnosis:

1. Check Basescan

   • Copy transaction hash from wallet
   • Visit https://basescan.org/tx/{hash}
   • Check status: Pending, Success, or Failed

2. Base Network Status

   • Visit https://status.base.org
   • Check for outages or congestion

Solutions:

If Transaction Truly Pending:

• Wait 10-15 minutes (Base usually confirms in ~2 seconds, but congestion can delay)
• Do NOT send duplicate transaction (will waste gas)

If Transaction Stuck (Rare):

• MetaMask: Settings → Advanced → Reset Account (clears pending nonce)
• Coinbase Wallet: Close app, reopen, check again

If Transaction Failed:

• Check error message on Basescan
• See "Common Transaction Errors" below

"Insufficient Funds" Error

Symptoms: Transaction fails with "insufficient funds for gas * price + value" error.

Cause: Not enough ETH in wallet to pay for gas fees.

Solutions:

1. Check ETH Balance

   • Need ETH on Base network (not Ethereum mainnet)
   • Minimum: ~$0.50-$1.00 ETH for gas

2. Bridge ETH to Base

   • Option 1: Coinbase (CEX) → Withdraw ETH directly to Base network
   • Option 2: Use Base bridge: https://bridge.base.org
   • Option 3: Third-party bridges (Across, Stargate, etc.)

3. Get ETH on Base

   • Buy on centralized exchange with Base withdrawals (Coinbase, Binance, etc.)
   • Use on-ramp services (Moonpay, Transak) with Base support

"Transaction Failed" with Error Message

Check Basescan error messages and solutions:

Gas Price Too High

Symptoms: Transaction estimate shows unusually high gas cost ($5+).

Causes:

• Network congestion (rare on Base)
• Complex transaction (batch operations)
• Wallet miscalculation

Solutions:

1. Wait for Lower Congestion

   • Check Base gas tracker (if available)
   • Try during off-peak hours (weekends, late night UTC)

2. Adjust Gas Settings (Advanced)

   • MetaMask: Edit gas fee → Set "Market" or "Aggressive"
   • Base typically doesn't require custom gas settings

3. Verify Transaction Type

   • Simple mint/stake/claim should cost $0.01-$0.50
   • If much higher, may indicate error - cancel and retry

NFT Minting Issues

"Claim Condition Not Active"

Cause: NFT Drop contract claim condition paused or expired.

Solutions:

1. Check Claim Status

   • Visit FarFISH homepage
   • Look for "Minting Active" indicator

2. Check Total Supply

   • If 9,999 / 9,999 minted → Sold out
   • No more mints possible

3. Wait for Announcement

   • Follow FarFISH Twitter/Discord for claim condition updates
   • New phases may open with different pricing

NFT Not Appearing After Mint

Symptoms: Transaction confirmed, but NFT not showing in wallet/profile.

Solutions:

1. Wait for Confirmation

   • Give 30-60 seconds for blockchain confirmations
   • Refresh page

2. Verify on Basescan

   • Go to transaction on Basescan
   • Check "Tokens Transferred" section
   • Should show NFT transfer to your address

3. Manually Add NFT to Wallet

   • MetaMask: Assets → Import NFT
   • Contract: See Contract Addresses
   • Token ID: Check Basescan transaction for token ID

4. Check Correct Wallet

   • Ensure wallet connected matches mint wallet
   • Check wallet network = Base Mainnet

Staking Issues

"Not Approved" Error When Staking

Cause: Staking contract not approved to transfer your NFT.

Solution:

Step 1: Approve Staking Contract

1. Go to `/stake` page
2. Click "Approve" button (appears before stake)
3. Confirm transaction in wallet
4. Wait for confirmation

Step 2: Stake NFT

1. After approval, "Stake" button becomes active
2. Select NFT rarity and lock duration
3. Confirm stake transaction

Can't Unstake NFT

Symptoms: "Unstake" button greyed out or transaction fails with "Lock period not expired".

Cause: Staking lock duration hasn't finished yet.

Solutions:

1. Check Unlock Time

   • View stake details on /stake page
   • Note "Unlock Date" timestamp
   • Wait until current date/time exceeds unlock timestamp

2. Time Zone Confusion

   • Unlock time displayed in your local time zone
   • Countdown timer shows exact remaining time

3. After Unlock Time Passes

   • "Unstake" button becomes enabled
   • Click and confirm transaction
   • NFT returns to your wallet

Lock Durations:

• 30 days = 2,592,000 seconds
• 90 days = 7,776,000 seconds
• 180 days = 15,552,000 seconds
• 360 days = 31,104,000 seconds

Staking Rewards Not Showing

Symptoms: Staked NFT but rewards show 0 or old amount.

Solutions:

1. Wait for Update

   • Rewards accrue per block (~2 seconds on Base)
   • Refresh page after 10-20 seconds

2. Check Stake Confirmation

   • Verify stake transaction confirmed on Basescan
   • getStakeInfo(stakeId) should return non-zero values

3. Claim Rewards

   • Rewards must be claimed via "Claim" button
   • Unclaimed rewards accumulate in contract

4. Calculate Expected Rewards

   text

   Copy

   Daily Rate (see tokenomics) × Days Elapsed = Expected Rewards
   Example: 10.67 FRH/day × 10 days = 106.7 FRH (for RedSpike 360-day stake)
   

Referral Issues

Referral Link Not Working

Symptoms: Friend clicks link, connects wallet, but no referral recorded.

Diagnosis:

1. Check Cache

   • Friend should see refCode in browser localStorage
   • DevTools → Application → localStorage → ff_pending_referral

2. Verify Recording

   • After wallet connection, call GET /api/referral/check?wallet={friend_address}
   • Should return {hasReferrer: true}

Common Causes & Solutions:

Cause: Link Clicked on Different Domain

• Web App link (app.farfish.xyz?ref=...) clicked by friend
• Friend connects wallet on Base App (baseapp.farfish.xyz) instead
• Solution: Both parties use same app variant

Cause: localStorage Cleared

• Friend cleared browser cache before connecting
• Solution: Click referral link again, connect immediately

Cause: Self-Referral

• Friend's wallet ends with same 8 characters as refCode
• API returns error: "Cannot refer yourself"
• Solution: Use different referral link or create new wallet

Cause: Already Has Referrer

• Friend was already referred by someone else
• Referrals are immutable (cannot change)
• Solution: Friend is ineligible for new referral

"Cannot Refer Yourself" Error

Cause: Your wallet address ends with the same 8 characters as the refCode you're trying to use.

Example:

• Your wallet: 0x1234567890abcdef1234567890abcdef12345678
• RefCode: 12345678
• System detects self-referral ❌

Solutions:

1. Verify RefCode

   • Ensure you're not using your own refCode
   • Your refCode = last 8 chars of your wallet (lowercase)

2. Use Different Link

   • Get referral link from different person

3. Extremely Rare Collision

   • If legitimate collision (1 in 4.3 billion chance), contact support

Daily Chest Issues

Can't Claim Bronze Chest (Cooldown Active)

Cause: Less than 24 hours since last bronze chest claim.

Solution:

1. Check Cooldown Timer

   • /chest page shows countdown: "Next claim in 12h 34m"
   • Wait until timer reaches 0

2. Verify Last Claim Time

   • Check Basescan for last DailyChestClaimed event
   • Cooldown = 24 hours from that timestamp

3. Time Zone Note

   • Cooldown is exact (86,400 seconds), not "midnight reset"
   • If you claim at 3:00 PM, next claim available at 3:00 PM next day

Can't Claim Silver Chest (No Active Stake)

Cause: Silver chest requires at least one active stake (any NFT, any duration).

Solution:

1. Stake an NFT

   • Go to /stake page
   • Stake any rarity for any duration
   • Active stakes unlock silver chest access

2. Verify Stake Active

   • Check /stake page shows staked NFT
   • Call getUserStakeIds(wallet) should return non-empty array

3. After Staking

   • Silver chest becomes claimable
   • Can claim every 24 hours while stake active

Android App Issues

App Not Loading / Blank Screen

Symptoms: FarFISH Android app shows white screen or infinite loading.

Solutions:

1. Clear App Cache

   • Settings → Apps → FarFISH → Storage → Clear Cache
   • Restart app

2. Check Internet Connection

   • Ensure WiFi or mobile data active
   • Try opening other apps to verify connectivity

3. Update App

   • Download latest APK from farfish.xyz/app-release.apk

4. Reinstall App

   • Uninstall FarFISH
   • Reboot phone
   • Reinstall from APK

5. Check Android Version

   • Minimum: Android 9.0 Pie
   • Settings → About Phone → Android Version
   • If older, device is unsupported

WalletConnect Not Working in Android App

Symptoms: Scanning QR code does nothing or fails to connect.

Solutions:

1. Ensure Wallet App Installed

   • MetaMask, Trust Wallet, or other WalletConnect-compatible wallet
   • Both apps must be updated to latest versions

2. Camera Permission

   • Settings → Apps → FarFISH → Permissions → Camera → Allow

3. Connection Flow

   • FarFISH app: Click "Connect Wallet" → "WalletConnect"
   • Scan QR with wallet app (NOT phone camera app)
   • Approve connection in wallet app

4. Alternative: Deep Links

   • Some wallets support wc:// deep links
   • Tap connection URL (if provided) instead of scanning

5. Fallback: Use Mobile Browser

   • Open app.farfish.xyz in wallet's in-app browser
   • Connect directly (no QR code needed)

Search and Navigation Issues

Search Returns No Results

Symptoms: Typing in search bar (Cmd/Ctrl+K) shows "No results".

Solutions:

1. Check Search Index Built

   • Search requires build-time index generation
   • If docs recently updated, search index may be stale

2. Try Different Keywords

   • Search for "NFT", "stake", "referral", "wallet"
   • Partial words may not match

3. Use Navigation

   • Sidebar navigation shows all pages
   • Browse manually if search fails

Page 404 Error

Symptoms: Clicking link shows "404 Page Not Found".

Causes:

1. Broken Link - Internal link points to non-existent page
2. Old URL - Documentation restructured, old URLs deprecated
3. Typo - URL manually typed incorrectly

Solutions:

1. Check URL

   • Verify spelling and path
   • Remove trailing slashes if present

2. Use Homepage

   • Go to root: /
   • Navigate from there

3. Report Broken Link

   • Note URL and referring page
   • Report to FarFISH support

Performance Issues

Page Loading Slowly

Solutions:

1. Check Internet Speed

   • Run speed test (speedtest.net)
   • FarFISH requires ~5 Mbps minimum

2. Clear Browser Cache

   • Chrome: Settings → Privacy → Clear browsing data
   • Select "Cached images and files"

3. Disable Extensions

   • Ad blockers, privacy tools may slow page load
   • Try incognito/private browsing mode

4. Try Different RPC

   • FarFISH uses 4-tier RPC fallback
   • If all slow, Base network may be congested

Still Need Help?

Before Contacting Support

Gather Information:

1. Wallet Address (safe to share - it's public)
2. Transaction Hash (if applicable)
3. Screenshot of error message
4. Browser & Version (Chrome 120, Firefox 118, etc.)
5. Device (Windows 11, MacBook M2, Android 14, etc.)

Contact Channels

• Discord: FarFISH Discord (check farfish.xyz for invite link)
• Telegram: FarFISH Telegram
• Twitter: @FarFISH (DM open for support)
• Email: support@farfish.xyz (if available)

Emergency (Security Issues)

Found a vulnerability? See Security Disclosure for responsible disclosure process.

Related Documentation

• FAQ - Quick answers to common questions
• Getting Started - Beginner setup guide
• Wallet Setup - Detailed wallet instructions
• Security Model - Understanding system security