Complete Troubleshooting Guide

Quick Fixes for Common Issues

🔥 Most Common Problems (90% of Issues)

Wallet Connection Issues

Problem: "Wallet Not Detected"

Symptoms:

• Connect button doesn't work
• No wallet popup appears
• "Please install wallet" message

Solutions:

Solution 1: Install Correct Wallet

# Supported wallets in order of compatibility:
1. Sui Wallet (Official) - 99% success rate
   → Download: https://chrome.google.com/webstore/[sui-wallet-id]

2. Suiet - 95% success rate
   → Download: https://suiet.app

3. Ethos - 90% success rate
   → Download: https://ethoswallet.xyz

Solution 2: Browser Compatibility

✅ Supported Browsers:
- Chrome v90+ (Recommended)
- Brave v1.40+
- Edge v90+
- Firefox v89+ (with limitations)

❌ Not Supported:
- Safari (no Web3 support)
- Mobile browsers (use wallet apps)
- Opera (untested)

Solution 3: Extension Conflicts

// Check for conflicts in console (F12)
console.log(window.sui);  // Should show wallet object

// If undefined, disable these extensions:
- MetaMask (can conflict)
- Other blockchain wallets
- Ad blockers (sometimes)
- VPNs (occasionally)

Problem: "Connection Rejected"

Symptoms:

• Wallet opens but connection fails
• "User rejected" error
• Stuck on "Connecting..."

Solutions:

Step-by-Step Fix:

1. Open wallet extension
2. Check network → Must be "Sui Mainnet"
3. Settings → Connected Sites → Remove suiverse.org
4. Refresh SuiVerse page
5. Connect again → Approve all permissions

Problem: "Wrong Network"

Fix in Sui Wallet:

1. Click network dropdown (top of wallet)
2. Select "Mainnet"
3. Wait for sync (5-10 seconds)
4. Refresh SuiVerse

Fix in Suiet:

1. Settings icon → Network
2. Choose "Sui Mainnet"
3. Save and close
4. Reconnect to SuiVerse

Transaction Failures

Problem: "Insufficient Gas"

Error Messages:

• "Insufficient gas payment"
• "Cannot pay gas"
• "Balance too low"

Understanding Gas:

Minimum Requirements:
├── Regular actions: 0.001 SUI
├── Content creation: 0.01 SUI
├── Quiz submission: 0.001 SUI
├── Exam entry: 5 SUI
└── Safety buffer: Keep 0.1 SUI always

Solutions:

Get Free SUI (Testnet Only)

# Testnet faucet for testing
curl -X POST https://faucet.testnet.sui.io/gas \
  -H "Content-Type: application/json" \
  -d '{"address": "YOUR_WALLET_ADDRESS"}'

Buy SUI (Mainnet)

Exchanges Supporting Direct Withdrawal to Sui:
1. Binance → Withdraw → Sui Network
2. OKX → Withdraw → Select Sui
3. KuCoin → Withdraw → Sui Mainnet
4. Bybit → Withdraw → Sui

⚠️ NEVER send from Ethereum/BSC/etc!

Problem: "Transaction Timeout"

Symptoms:

• Spinning for >30 seconds
• "Transaction pending" forever
• No confirmation

Quick Fix:

// 1. Check transaction status
https://suiexplorer.com/txblock/[your-tx-hash]

// 2. If not found after 60 seconds:
- Transaction failed silently
- Try again with higher gas
- Check network congestion

Advanced Fix:

// Retry with custom gas budget
const tx = {
    ...originalTx,
    gasBudget: 10000000, // Increase from default
    gasPrice: 1000 // Increase if congested
};

Problem: "Object Version Mismatch"

What This Means:

• Object was modified by another transaction
• Concurrent access conflict
• Stale data in cache

Solution:

1. Refresh page (F5)
2. Clear browser cache
   - Chrome: Ctrl+Shift+Delete
   - Select "Cached images and files"
   - Clear last hour
3. Retry transaction
4. If persists: Wait 30 seconds (object lock release)

Content Display Issues

Problem: "Content Not Loading"

Diagnostic Steps:

Browser Cache Clear:

Chrome/Edge:
1. Press: Ctrl + Shift + Delete
2. Time range: "Last hour"
3. Check: "Cached images and files"
4. Clear data
5. Refresh: Ctrl + F5

Firefox:
1. Press: Ctrl + Shift + Delete
2. Time range: "Last hour"
3. Check: "Cache"
4. Clear Now
5. Refresh: Ctrl + F5

Problem: "Images/Diagrams Not Showing"

Common Causes:

1. IPFS Gateway Issues (30% of cases)
   - Solution: Wait 5 minutes, refresh
   
2. Browser Blocking (25% of cases)
   - Solution: Disable shields/ad-block for site
   
3. Network Restrictions (20% of cases)
   - Solution: Try different network/VPN
   
4. Corrupted Cache (25% of cases)
   - Solution: Clear cache and cookies

Problem: "Quiz Not Responding"

Fix Sequence:

1. Check console for errors (F12)
2. Ensure wallet is connected
3. Verify you have gas (>0.01 SUI)
4. Clear localStorage:
   - F12 → Application → Local Storage
   - Right-click suiverse.org → Clear
5. Refresh and retry

Earning & Rewards Issues

Problem: "Not Earning from Content"

Diagnostic Checklist:

□ Content is validated (score 7+)
□ Content is published (not draft)
□ Has views this epoch (7 days)
□ ContentView system active
□ Wallet address correct
□ Not banned/restricted

View Tracking Debug:

// Check if views are being counted (F12 Console)
localStorage.getItem('suiverse_session');
// Should show session ID

// Check content metadata
fetch('/api/content/[content-id]/stats')
  .then(r => r.json())
  .then(console.log);
// Should show view count

Problem: "Certificate Not Issued"

Requirements Check:

Exam Passed? → Score ≥70%
Fee Paid? → 5 SUI deducted
Transaction Confirmed? → Check explorer
NFT Minted? → Check wallet NFTs
Kiosk Created? → May take 5 minutes

Manual Certificate Check:

// Check on-chain
const provider = new JsonRpcProvider();
const objects = await provider.getOwnedObjects({
    owner: "YOUR_ADDRESS",
    filter: { StructType: "0x2::kiosk::Certificate" }
});
console.log(objects);

Platform Performance Issues

Problem: "Site Running Slowly"

Performance Optimization:

1. Browser Choice Impact:
   Chrome: Fastest (100% baseline)
   Brave: Fast (95%)
   Firefox: Good (85%)
   Edge: Good (85%)

2. Extensions Impact:
   Each extension: -5% to -10% speed
   Disable unnecessary ones

3. Network Impact:
   Fiber/Cable: Optimal
   5G/4G: Good
   3G: May have issues
   Satellite: High latency

Quick Performance Boost:

// Clear all site data (nuclear option)
// ⚠️ You'll need to reconnect wallet
chrome://settings/content/all
→ Search: suiverse.org
→ Delete all data
→ Restart browser

Smart Contract Interactions

Problem: "Contract Call Failed"

Common Contract Errors:

Error Code	Meaning	Solution
0x1	Insufficient privileges	Check wallet is owner
0x2	Object not found	Object was deleted/moved
0x3	Type mismatch	Version incompatibility
0x4	Out of gas	Increase gas budget
0x5	Abort	Contract rejected action

Debug Contract Calls:

try {
    const result = await contract.method();
} catch (error) {
    console.log("Error code:", error.code);
    console.log("Error message:", error.message);
    console.log("Stack:", error.stack);
    
    // Parse Sui specific error
    if (error.message.includes("Abort")) {
        // Contract rejected the transaction
        // Check requirements in contract
    }
}

Account & Profile Issues

Problem: "Profile Not Updating"

Cache Refresh Sequence:

1. Local Update:
   - Edit profile
   - Click save
   - Wait for TX confirmation

2. Force Refresh:
   - Ctrl + F5 (hard refresh)
   - Still old? → Clear cookies

3. Blockchain Sync:
   - May take 30-60 seconds
   - Check explorer for TX

4. CDN Cache:
   - May take 5 minutes
   - Try incognito mode to verify

Problem: "Lost Access to Content"

Recovery Steps:

Wallet Recovery:

⚠️ NEVER share your seed phrase with ANYONE!

1. Install same wallet type
2. Choose "Import wallet"
3. Enter 12/24 word seed phrase
4. Set new password
5. Wallet restored with all content

Validation Issues

Problem: "Content Rejected"

Common Rejection Reasons:

Code Quality (40% of rejections):
├── Syntax errors in examples
├── Code doesn't run
├── Missing dependencies
└── Fix: Test all code locally first

Content Quality (30% of rejections):
├── Plagiarism detected
├── Poor grammar/spelling
├── Unclear explanations
└── Fix: Use grammar checker, be original

Formatting (20% of rejections):
├── Broken markdown
├── Images not loading
├── Bad structure
└── Fix: Preview before submit

Relevance (10% of rejections):
├── Off-topic content
├── Outdated information
├── Wrong category
└── Fix: Check category guidelines

Network & Connectivity

Problem: "IPFS Gateway Timeout"

Alternative Gateways:

// If default gateway fails, try these:
const gateways = [
    "https://ipfs.io/ipfs/",
    "https://gateway.pinata.cloud/ipfs/",
    "https://cloudflare-ipfs.com/ipfs/",
    "https://gateway.ipfs.io/ipfs/"
];

// Fallback logic
async function fetchIPFS(hash) {
    for (const gateway of gateways) {
        try {
            const response = await fetch(gateway + hash);
            if (response.ok) return response;
        } catch (e) {
            continue;
        }
    }
    throw new Error("All gateways failed");
}

Problem: "WebSocket Disconnected"

Reconnection Strategy:

let ws;
let reconnectAttempts = 0;

function connect() {
    ws = new WebSocket('wss://suiverse.org/ws');
    
    ws.onclose = () => {
        if (reconnectAttempts < 5) {
            setTimeout(() => {
                reconnectAttempts++;
                connect();
            }, 1000 * Math.pow(2, reconnectAttempts));
        }
    };
    
    ws.onopen = () => {
        reconnectAttempts = 0;
    };
}

Advanced Debugging

Browser Console Commands

Useful Debugging Commands:

// Check SuiVerse state
window.__SUIVERSE_STATE__

// Check wallet connection
window.sui.isConnected()

// Get current account
await window.sui.getAccounts()

// Check network
await window.sui.getNetwork()

// Clear all local data
localStorage.clear()
sessionStorage.clear()

// Force reload without cache
location.reload(true)

Network Inspector

How to Debug Network Issues:

1. Open DevTools (F12)
2. Go to Network tab
3. Reload page
4. Look for red requests (failed)
5. Click on failed request
6. Check Response tab for error

Common Issues:
- 403: Access denied (check wallet)
- 404: Content not found
- 429: Rate limited (wait)
- 500: Server error (report)
- 503: Maintenance (wait)

Getting Help

Self-Service Resources

Before Asking for Help:

1. Check this troubleshooting guide
2. Search Discord for your error
3. Check GitHub issues
4. Try incognito mode
5. Try different browser
6. Try different network

Community Support

Discord Channels:

#tech-support - General issues
#wallet-help - Wallet problems
#content-help - Creator issues
#bug-reports - Platform bugs

Support Response Times:

• Critical issues: Within 1 hour
• Normal issues: Within 6 hours
• Low priority: Within 24 hours

Reporting Bugs

Good Bug Report Template:

**Description:** Clear description of issue

**Steps to Reproduce:**
1. Go to...
2. Click on...
3. See error...

**Expected:** What should happen
**Actual:** What actually happens

**Environment:**
- Browser: Chrome 120
- Wallet: Sui Wallet 1.0
- Network: Mainnet
- Time: 2024-01-20 15:30 UTC

**Screenshots:** [Attach if relevant]
**Console Errors:** [Copy from F12]

Emergency Procedures

Lost Funds Recovery

If You Lost SUI:

1. Check transaction history in wallet
2. Verify address was correct
3. Check explorer for transaction
4. If sent to wrong address: Cannot recover
5. If transaction failed: Funds returned minus gas

Account Compromise

If Wallet Compromised:

IMMEDIATE ACTIONS:
1. Transfer all assets to new wallet
2. Revoke all app permissions
3. Never use that seed phrase again
4. Report to Discord admins
5. Monitor old address for activity

Preventive Measures

Best Practices Checklist

Daily:

• Keep >0.1 SUI for gas
• Check content performance
• Respond to comments

Weekly:

• Update browser
• Clear old cache
• Check for platform updates
• Backup important data

Monthly:

• Review wallet security
• Update passwords
• Check connected apps
• Clean browser extensions

---

Quick Reference Card

Error Codes Cheat Sheet

E001: Wallet not found → Install wallet
E002: Wrong network → Switch to mainnet
E003: Insufficient gas → Add SUI
E004: Transaction failed → Retry
E005: Content not found → Refresh
E006: Not authorized → Connect wallet
E007: Rate limited → Wait 1 minute
E008: Server error → Report to team

Keyboard Shortcuts

Ctrl+Shift+R: Hard refresh
Ctrl+Shift+I: Open console
Ctrl+Shift+Delete: Clear cache
F5: Refresh page
F12: Developer tools

Important Links

Status Page: status.suiverse.org
Support: support.suiverse.org
Discord: discord.gg/suiverse
Explorer: suiexplorer.com

💡 Golden Rule: When in doubt, refresh and reconnect! Solves 80% of issues.