TurboTrades/frontend/TROUBLESHOOTING.md

# TurboTrades Frontend - Troubleshooting Guide

This guide covers common issues and their solutions when working with the TurboTrades frontend.

## 🔴 CSS/Tailwind Issues

### Issue: "The `border-border` class does not exist"

**Error Message:**
```
[postcss] The `border-border` class does not exist
```

**Solution:**
This has been fixed in the latest version. If you still see this error:

1. Clear Vite cache:
```bash
rm -rf node_modules/.vite
```

2. Restart the dev server:
```bash
npm run dev
```

### Issue: Tailwind classes not applying

**Symptoms:**
- Styles not showing up
- Page looks unstyled
- Colors are wrong

**Solutions:**

1. **Restart the dev server** (most common fix):
   - Press `Ctrl+C` to stop
   - Run `npm run dev` again

2. **Check Tailwind configuration:**
   - Verify `tailwind.config.js` exists
   - Check content paths include all Vue files

3. **Clear cache and restart:**
```bash
rm -rf node_modules/.vite
npm run dev
```

### Issue: "Unknown at rule @tailwind"

**Solution:**
This is usually an IDE warning and can be ignored. To fix:

1. **VS Code:** Install "Tailwind CSS IntelliSense" extension
2. **Add to settings.json:**
```json
{
  "css.validate": false,
  "scss.validate": false
}
```

## 🔴 Installation Issues

### Issue: "Cannot find module 'vue'"

**Error Message:**
```
Error: Cannot find module 'vue'
```

**Solution:**
Dependencies not installed properly.

```bash
# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install
```

### Issue: EACCES permission errors (Unix/macOS)

**Error Message:**
```
npm ERR! code EACCES
npm ERR! syscall access
```

**Solution:**

1. **Fix npm permissions** (recommended):
```bash
sudo chown -R $USER:$(id -gn $USER) ~/.npm
sudo chown -R $USER:$(id -gn $USER) ~/.config
```

2. **Or use sudo** (not recommended):
```bash
sudo npm install
```

### Issue: "EPERM: operation not permitted" (Windows)

**Solution:**

1. Close all applications that might be using files
2. Run Command Prompt as Administrator
3. Try installation again

## 🔴 Development Server Issues

### Issue: Port 5173 already in use

**Error Message:**
```
Port 5173 is in use, trying another one...
```

**Solutions:**

1. **Kill the process using port 5173:**

**Windows:**
```cmd
netstat -ano | findstr :5173
taskkill /PID <PID> /F
```

**macOS/Linux:**
```bash
lsof -ti:5173 | xargs kill -9
```

2. **Use a different port:**
```bash
npm run dev -- --port 5174
```

### Issue: "Address already in use"

**Solution:**
Another Vite server is running. Close all terminal windows running Vite and try again.

### Issue: Dev server starts but browser shows "Cannot GET /"

**Solutions:**

1. Check you're accessing the correct URL: `http://localhost:5173`
2. Clear browser cache (Ctrl+Shift+Delete)
3. Try incognito/private mode

## 🔴 API Connection Issues

### Issue: "Network Error" or "Failed to fetch"

**Symptoms:**
- Login doesn't work
- API calls fail
- Console shows network errors

**Solutions:**

1. **Verify backend is running:**
```bash
# In another terminal
cd ../
npm run dev
```

Backend should be running on `http://localhost:3000`

2. **Check proxy configuration** in `vite.config.js`:
```javascript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}
```

3. **Verify backend CORS settings:**
Backend should allow `http://localhost:5173` origin.

### Issue: API calls return 404

**Solution:**

1. Check backend routes are correctly defined
2. Verify API endpoint paths in frontend code
3. Check proxy rewrite rules in `vite.config.js`

## 🔴 WebSocket Issues

### Issue: "WebSocket connection failed"

**Error in Console:**
```
WebSocket connection to 'ws://localhost:3000/ws' failed
```

**Solutions:**

1. **Verify backend WebSocket server is running:**
   - Check backend console for WebSocket initialization
   - Backend should show: "WebSocket server initialized"

2. **Check WebSocket URL:**
   - Development: `ws://localhost:3000/ws`
   - Production: `wss://yourdomain.com/ws`

3. **Verify proxy configuration** in `vite.config.js`:
```javascript
'/ws': {
  target: 'ws://localhost:3000',
  ws: true,
}
```

### Issue: WebSocket connects but immediately disconnects

**Solution:**

1. Check backend WebSocket authentication
2. Verify token is being sent correctly
3. Check backend logs for connection errors

## 🔴 Authentication Issues

### Issue: Login redirects to error page

**Solutions:**

1. **Verify Steam API key** in backend `.env`:
```env
STEAM_API_KEY=your_actual_steam_api_key
```

2. **Check Steam realm settings:**
```env
STEAM_REALM=http://localhost:3000
STEAM_RETURN_URL=http://localhost:3000/auth/steam/return
```

3. **Verify MongoDB is running:**
```bash
mongod --version
# Should show version, not error
```

### Issue: "Token expired" errors

**Solution:**
This is normal after 15 minutes. The app should auto-refresh the token.

If auto-refresh fails:
1. Clear cookies
2. Log out and log back in
3. Check backend JWT secrets are set

### Issue: User data not persisting after refresh

**Solution:**

1. Cookies might not be set correctly
2. Check browser console for cookie errors
3. Verify `withCredentials: true` in axios config
4. Check backend cookie settings (httpOnly, sameSite)

## 🔴 Build Issues

### Issue: Build fails with "Out of memory"

**Error:**
```
FATAL ERROR: Reached heap limit Allocation failed
```

**Solution:**
Increase Node.js memory:

```bash
# Windows
set NODE_OPTIONS=--max-old-space-size=4096

# macOS/Linux
export NODE_OPTIONS=--max-old-space-size=4096

# Then build
npm run build
```

### Issue: Build succeeds but preview doesn't work

**Solution:**

```bash
# Clean and rebuild
rm -rf dist
npm run build
npm run preview
```

## 🔴 Component Issues

### Issue: Components not hot reloading

**Solutions:**

1. Save the file (Ctrl+S)
2. Check for syntax errors in console
3. Restart dev server
4. Check if file is in `src/` directory

### Issue: "v-model" not working

**Solution:**
Ensure you're using Vue 3 syntax:

```vue
<!-- Correct (Vue 3) -->
<input v-model="value" />

<!-- Incorrect (Vue 2 - don't use) -->
<input :value="value" @input="value = $event.target.value" />
```

### Issue: Pinia store not updating

**Solutions:**

1. Verify you're using the store correctly:
```javascript
import { useAuthStore } from '@/stores/auth'

const authStore = useAuthStore()
// Use authStore.property, not authStore.value.property
```

2. Ensure state is reactive:
```javascript
const user = ref(null) // ✅ Reactive
const user = null       // ❌ Not reactive
```

## 🔴 Routing Issues

### Issue: 404 on page refresh

**Solution:**
This is expected in development with Vite. In production, configure your server:

**Nginx:**
```nginx
location / {
  try_files $uri $uri/ /index.html;
}
```

**Apache (.htaccess):**
```apache
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]
```

### Issue: Router links not working

**Solution:**

1. Use `<router-link>` not `<a>`:
```vue
<!-- Correct -->
<router-link to="/market">Market</router-link>

<!-- Incorrect -->
<a href="/market">Market</a>
```

2. Use `router.push()` in script:
```javascript
import { useRouter } from 'vue-router'

const router = useRouter()
router.push('/market')
```

## 🔴 Performance Issues

### Issue: App is slow or laggy

**Solutions:**

1. **Check browser DevTools Performance tab**
2. **Reduce console.log statements** in production
3. **Enable Vue DevTools Performance tab**
4. **Check for memory leaks:**
   - Unsubscribe from WebSocket events
   - Remove event listeners in `onUnmounted`

### Issue: Initial load is slow

**Solutions:**

1. **Verify it's only slow on first load** (expected)
2. **Check network tab** for large assets
3. **Production build is much faster:**
```bash
npm run build
npm run preview
```

## 🔴 Browser-Specific Issues

### Issue: Works in Chrome but not Firefox/Safari

**Solutions:**

1. Check browser console for errors
2. Verify browser version (Firefox 88+, Safari 14+)
3. Check for browser-specific CSS issues
4. Test in private/incognito mode

### Issue: Styles different in Safari

**Solution:**
Safari has different default styles. This is expected. Most major issues are already handled.

## 🔴 IDE Issues

### Issue: VS Code not recognizing Vue files

**Solution:**

1. Install **Volar** extension (NOT Vetur for Vue 3)
2. Disable Vetur if installed
3. Restart VS Code

### Issue: ESLint errors everywhere

**Solution:**

1. Install dependencies:
```bash
npm install
```

2. Restart VS Code

3. Check `.eslintrc.cjs` exists

## 🚨 Emergency Fixes

### Nuclear Option: Complete Reset

If nothing else works:

```bash
# 1. Stop all servers (Ctrl+C)

# 2. Delete everything
rm -rf node_modules
rm -rf dist
rm -rf .vite
rm package-lock.json

# 3. Clean npm cache
npm cache clean --force

# 4. Reinstall
npm install

# 5. Start fresh
npm run dev
```

### Check System Requirements

```bash
# Check Node version (should be 18+)
node -v

# Check npm version (should be 9+)
npm -v

# Check available disk space
# Windows: dir
# macOS/Linux: df -h

# Check available memory
# Windows: systeminfo
# macOS/Linux: free -h
```

## 📞 Getting Help

If none of these solutions work:

1. **Check the documentation:**
   - `README.md` - Full documentation
   - `QUICKSTART.md` - Quick start guide
   - `INSTALLATION.md` - Installation guide

2. **Search for similar issues:**
   - GitHub Issues
   - Stack Overflow
   - Vue.js Discord

3. **Create a bug report with:**
   - Operating system
   - Node.js version
   - Complete error message
   - Steps to reproduce
   - What you've already tried

4. **Contact support:**
   - GitHub Issues: Create new issue
   - Email: support@turbotrades.com
   - Discord: [Your Discord link]

## 📝 Preventive Measures

To avoid issues:

1. ✅ Use Node.js 18 or higher
2. ✅ Keep dependencies updated
3. ✅ Clear cache regularly
4. ✅ Use version control (Git)
5. ✅ Test in multiple browsers
6. ✅ Keep backend and frontend versions in sync
7. ✅ Read error messages carefully
8. ✅ Check backend logs when API fails

## 🎯 Quick Diagnosis

**If you see errors:**
1. Read the error message completely
2. Check which file/line number
3. Look for typos first
4. Search this guide for the error
5. Check browser console
6. Check backend logs
7. Restart dev server

**If something doesn't work:**
1. Does it work in the same browser after refresh?
2. Does it work in another browser?
3. Does it work after restarting the dev server?
4. Is the backend running?
5. Are there errors in console?

---

**Last Updated:** January 2025  
**Version:** 1.0.0

Remember: Most issues are solved by restarting the dev server! 🔄