archy-demo/neode-ui/TROUBLESHOOTING.md

Neode UI Troubleshooting

Common Issues and Solutions

1. "Method not found: marketplace.get"

Cause: The backend isn't running or doesn't have the marketplace API enabled.

Solutions:

Option A: Start the Backend

# Ensure the Neode backend is running
cd /Users/tx1138/Code/Neode
# Start your backend service (adjust command as needed)

Option B: Check Backend Status

# Test if backend is accessible
curl -X POST http://localhost:5959/rpc/v1 \
  -H "Content-Type: application/json" \
  -d '{"method":"echo","params":{"message":"test"}}'

# Should return: {"result":"test"}

Option C: Use Mock Mode (Development Only)

Enable mock mode in src/views/Marketplace.vue by uncommenting the mock data section (see below).

---

2. WebSocket Error: "Cannot read properties of undefined (reading 'length')"

Cause: WebSocket patch data is malformed or empty.

Fixed: This is now handled gracefully. The app will log a warning but continue working.

What Changed:

• Added validation in src/api/websocket.ts → applyDataPatch()
• Added try/catch in src/stores/app.ts → connectWebSocket()

If you still see this error:

1. Check browser console for details
2. Verify backend is sending correct patch format
3. The app will continue working without real-time updates

---

3. "Please login first to access the marketplace"

Cause: You're not authenticated yet.

Solution:

1. Navigate to /login
2. Enter your password
3. Return to marketplace

Check Auth Status:

// In browser console
const store = useAppStore()
console.log('Authenticated:', store.isAuthenticated)

---

4. "Cannot connect to backend"

Cause: Backend isn't running or proxy isn't configured.

Solutions:

Check Vite Proxy

Verify vite.config.ts has:

proxy: {
  '/rpc/v1': 'http://localhost:5959',
  '/ws/db': {
    target: 'ws://localhost:5959',
    ws: true
  }
}

Test Backend Connection

# Check if backend is listening
lsof -i :5959

# Or use netstat
netstat -an | grep 5959

Start Backend Manually

cd /Users/tx1138/Code/Neode/core
cargo run --release --bin startos

---

Development Without Backend

Enable Mock Mode

If you want to develop the UI without a running backend, you can enable mock mode:

Edit src/views/Marketplace.vue:

async function loadMarketplace() {
  loading.value = true
  error.value = null
  apps.value = []

  // MOCK MODE - Comment out in production
  const MOCK_MODE = true // Set to false when backend is available
  
  if (MOCK_MODE) {
    // Simulate loading delay
    await new Promise(resolve => setTimeout(resolve, 1000))
    
    apps.value = [
      {
        id: 'bitcoin',
        title: 'Bitcoin Core',
        description: 'A full Bitcoin node implementation. Store, validate, and relay blocks and transactions.',
        version: '25.0.0',
        icon: '/assets/img/bitcoin.png',
      },
      {
        id: 'lightning',
        title: 'Lightning Network',
        description: 'Lightning Network implementation for fast, low-cost Bitcoin payments.',
        version: '0.17.0',
        icon: '/assets/img/lightning.png',
      },
      {
        id: 'nextcloud',
        title: 'Nextcloud',
        description: 'Self-hosted file sync and sharing platform.',
        version: '27.1.0',
        icon: '/assets/img/nextcloud.png',
      },
    ]
    loading.value = false
    return
  }
  // END MOCK MODE

  // Real implementation continues...
  try {
    // ...
  }
}

---

Debugging Tips

Enable Verbose Logging

Add to src/api/rpc-client.ts:

async call<T>(options: RPCOptions): Promise<T> {
  console.log('🔵 RPC Request:', options) // Add this
  
  const response = await fetch(this.baseUrl, {
    // ...
  })
  
  const data = await response.json()
  console.log('🟢 RPC Response:', data) // Add this
  
  return data.result as T
}

Check WebSocket Status

In browser console:

// Check WebSocket connection
const store = useAppStore()
console.log('Connected:', store.isConnected)
console.log('Data:', store.data)

Monitor Network Traffic

1. Open Chrome DevTools (F12)
2. Go to Network tab
3. Filter by "WS" for WebSocket
4. Filter by "XHR" for RPC calls
5. Inspect request/response payloads

---

Backend Build Issues

Build Rust Backend

cd /Users/tx1138/Code/Neode/core
cargo build --release

# Binary will be at:
# target/release/startos

Run Backend for Development

# Run with debug logging
RUST_LOG=debug ./target/release/startos

# Or use cargo run
RUST_LOG=debug cargo run --release

---

Port Conflicts

Check What's Using Port 5959

# macOS
lsof -i :5959

# Kill process if needed
kill -9 <PID>

Check What's Using Port 8100 (Vite)

lsof -i :8100
kill -9 <PID>

---

Authentication Issues

Clear Session Cookies

In browser DevTools:

1. Application tab → Cookies
2. Delete all cookies for localhost:8100
3. Refresh page and login again

Check Auth Cookie

In browser console:

// Check if auth cookie exists
document.cookie

---

WebSocket Connection Fails

Common Causes

1. Backend not running: Start backend on port 5959
2. CORS issues: Vite proxy should handle this
3. Port mismatch: Check backend is listening on 5959

Debug WebSocket

Add to src/api/websocket.ts:

this.ws.onopen = () => {
  console.log('✅ WebSocket connected')
  this.reconnectAttempts = 0
  resolve()
}

this.ws.onerror = (error) => {
  console.error('❌ WebSocket error:', error)
  reject(error)
}

this.ws.onmessage = (event) => {
  console.log('📨 WebSocket message:', event.data) // Add this
  try {
    const update = JSON.parse(event.data)
    this.callbacks.forEach((callback) => callback(update))
  } catch (error) {
    console.error('Failed to parse message:', error)
  }
}

---

Build Errors

TypeScript Errors

# Type check without building
npm run type-check

# Fix common issues
npm install
rm -rf node_modules package-lock.json
npm install

Vite Build Fails

# Clear cache and rebuild
rm -rf dist node_modules/.vite
npm run build

---

Performance Issues

Slow Hot Reload

1. Check file watchers:

   # macOS - increase file watcher limit
   ulimit -n 4096
   

2. Clear Vite cache:

   rm -rf node_modules/.vite
   

High Memory Usage

• Close other tabs/applications
• Restart Vite dev server
• Check for memory leaks in DevTools → Memory

---

Still Having Issues?

Collect Debug Information

1. Browser Console Logs:

   • Open DevTools → Console
   • Copy all errors

2. Network Tab:

   • Check failed requests
   • Copy request/response details

3. Backend Logs:

   # If using systemd
   journalctl -u startos -f
   
   # If running manually
   # Check terminal output
   

4. System Info:

   node --version
   npm --version
   cargo --version
   

Clean Restart

# Stop everything
# Kill Vite dev server (Ctrl+C)
# Kill backend process

# Clean rebuild
cd /Users/tx1138/Code/Neode/neode-ui
rm -rf dist node_modules/.vite
npm install
npm run dev

# In another terminal, start backend
cd /Users/tx1138/Code/Neode/core
cargo run --release

---

Quick Reference

Start Development

# Terminal 1: UI
cd /Users/tx1138/Code/Neode/neode-ui
npm run dev

# Terminal 2: Backend (if available)
cd /Users/tx1138/Code/Neode/core
cargo run --release

Check Service Status

# Check if UI is running
curl http://localhost:8100

# Check if backend is running
curl http://localhost:5959/rpc/v1 -X POST \
  -H "Content-Type: application/json" \
  -d '{"method":"echo","params":{"message":"test"}}'

Reset Everything

# Clean all state
rm -rf neode-ui/dist neode-ui/node_modules/.vite
cd neode-ui && npm install && npm run dev