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:

rm -rf node_modules/.vite

2. Restart the dev server:

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:

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:

{
  "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.

# 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):

sudo chown -R $USER:$(id -gn $USER) ~/.npm
sudo chown -R $USER:$(id -gn $USER) ~/.config

2. Or use sudo (not recommended):

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:

netstat -ano | findstr :5173
taskkill /PID <PID> /F

macOS/Linux:

lsof -ti:5173 | xargs kill -9

2. Use a different port:

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:

# In another terminal
cd ../
npm run dev

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

2. Check proxy configuration in vite.config.js:

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:

'/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:

STEAM_API_KEY=your_actual_steam_api_key

2. Check Steam realm settings:

STEAM_REALM=http://localhost:3000
STEAM_RETURN_URL=http://localhost:3000/auth/steam/return

3. Verify MongoDB is running:

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:

# 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:

# 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:

<!-- 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:

import { useAuthStore } from '@/stores/auth'

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

2. Ensure state is reactive:

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:

location / {
  try_files $uri $uri/ /index.html;
}

Apache (.htaccess):

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>:

<!-- Correct -->
<router-link to="/market">Market</router-link>

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

2. Use router.push() in script:

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:

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:

npm install

2. Restart VS Code

3. Check .eslintrc.cjs exists

🚨 Emergency Fixes

Nuclear Option: Complete Reset

If nothing else works:

# 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

# 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! 🔄