Troubleshooting Guide

Overview

This guide provides solutions to common issues you might encounter while developing or deploying Q-Sopa.

API Connection Issues

Categories not loading

Problem: Categories fail to load and you see “Cargando…” indefinitely or an error message.Diagnosis: Check the browser console for error messages.Solutions:

Verify API endpoint in src/services/api.js:

const BASE_URL = "https://apiqsp-production.up.railway.app";

Test the API directly:

curl https://apiqsp-production.up.railway.app/categories

Check network requests in browser DevTools (Network tab):

Look for failed requests (red status codes)
Verify the request URL is correct
Check response status (should be 200)

Common fixes:

// Add better error handling
export const getCategorias = async () => {
  try {
    const res = await fetch(`${BASE_URL}/categories`);
    if (!res.ok) {
      console.error('Response status:', res.status);
      throw new Error(`HTTP error! status: ${res.status}`);
    }
    return res.json();
  } catch (error) {
    console.error('Failed to fetch categories:', error);
    throw error;
  }
};

Products not displaying

Problem: Categories load but products don’t appear when clicking a category.Check these in src/pages/Menu.jsx:

Verify state management:

const [products, setProducts] = useState([]);
const [activeCategoryId, setActiveCategoryId] = useState(null);

Check the useEffect dependency:

useEffect(() => {
  if (activeCategoryId === null) return;
  
  setLoading(true);
  setError(null);
  
  getProductsByCategory(activeCategoryId)
    .then((data) => {
      console.log('Products loaded:', data); // Add this for debugging
      setProducts(data);
    })
    .catch((err) => {
      console.error('Error loading products:', err);
      setError(err.message);
    })
    .finally(() => setLoading(false));
}, [activeCategoryId]);

Verify API returns correct data format: The API should return an array of products:

[
  {
    "id": 1,
    "name": "Classic Burger",
    "price": 12.99,
    "imageUrl": "https://...",
    "badge": "Popular"
  }
]

Check category ID is being passed correctly:

// In Categories.jsx
const handleClick = (id) => {
  console.log('Category clicked:', id); // Debug log
  setActive(id);
  onCategoryChange?.(id); // Make sure this passes the ID
};

API timeout errors

Problem: Requests time out or take too long.Solution: Add timeout handling:

// src/services/api.js
const fetchWithTimeout = async (url, timeout = 5000) => {
  const controller = new AbortController();
  const id = setTimeout(() => controller.abort(), timeout);
  
  try {
    const response = await fetch(url, {
      signal: controller.signal
    });
    clearTimeout(id);
    return response;
  } catch (error) {
    clearTimeout(id);
    if (error.name === 'AbortError') {
      throw new Error('Request timeout');
    }
    throw error;
  }
};

export const getCategorias = async () => {
  const res = await fetchWithTimeout(`${BASE_URL}/categories`);
  if (!res.ok) throw new Error("Error al cargar categorías");
  return res.json();
};

CORS Errors

CORS policy blocked request

Error: “Access to fetch at ‘https://…’ from origin ‘http://localhost:5173’ has been blocked by CORS policy”Cause: The API server doesn’t allow requests from your domain.Solutions:

1. Backend Configuration (Recommended)

If you control the API, add CORS headers:Express.js:

const cors = require('cors');

app.use(cors({
  origin: ['http://localhost:5173', 'https://your-production-domain.com'],
  credentials: true
}));

Fastify:

await fastify.register(require('@fastify/cors'), {
  origin: ['http://localhost:5173', 'https://your-production-domain.com']
});

2. Development Proxy

Use Vite’s proxy feature for development. Update vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': {
        target: 'https://apiqsp-production.up.railway.app',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

Then update src/services/api.js:

const BASE_URL = import.meta.env.DEV 
  ? '/api' 
  : 'https://apiqsp-production.up.railway.app';

3. Verify Request Headers

Check if credentials are needed:

export const getCategorias = async () => {
  const res = await fetch(`${BASE_URL}/categories`, {
    mode: 'cors',
    credentials: 'include' // Only if API requires cookies
  });
  if (!res.ok) throw new Error("Error al cargar categorías");
  return res.json();
};

Preflight OPTIONS request failing

Problem: CORS preflight requests are being rejected.Solution: Ensure your API handles OPTIONS requests:

// Express.js example
app.options('*', cors());

// Or manually:
app.options('*', (req, res) => {
  res.header('Access-Control-Allow-Origin', req.headers.origin);
  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  res.sendStatus(200);
});

Build Errors

Module not found errors

Error: Error: Cannot find module '@vitejs/plugin-react'Solutions:

Clean install dependencies:

rm -rf node_modules package-lock.json
npm install

Verify package.json:

{
  "devDependencies": {
    "@vitejs/plugin-react": "^5.1.1",
    "vite": "^7.3.1"
  }
}

Check Node version:

node --version  # Should be 16+ or 18+

Clear npm cache:

npm cache clean --force
npm install

Tailwind CSS not working

Problem: Tailwind classes are not being applied.Note: Q-Sopa uses Tailwind CSS v4. Check configuration:

Verify installation:

npm list tailwindcss

Check import in src/index.css:

@import "tailwindcss";

Ensure CSS is imported in src/main.jsx:

import './index.css'

Rebuild:

npm run build

Build fails with memory errors

Error: “JavaScript heap out of memory”Solution: Increase Node.js memory limit:

# Unix/Mac
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

# Windows (PowerShell)
$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Or update package.json:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' vite build"
  }
}

Development Server Issues

Port already in use

Error: Port 5173 is already in useSolutions:

Kill the process using the port:

# Find process
lsof -i :5173  # Mac/Linux
netstat -ano | findstr :5173  # Windows

# Kill process
kill -9 <PID>  # Mac/Linux
taskkill /PID <PID> /F  # Windows

Use a different port in vite.config.js:

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000
  }
})

Let Vite choose automatically:

export default defineConfig({
  plugins: [react()],
  server: {
    strictPort: false
  }
})

Hot reload not working

Problem: Changes don’t reflect immediately in the browser.Solutions:

Check file watching in vite.config.js:

export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      usePolling: true  // Enable for Docker/VMs
    }
  }
})

Clear browser cache:

Open DevTools
Right-click refresh button
Select “Empty Cache and Hard Reload”

Restart dev server:

# Stop with Ctrl+C, then:
npm run dev

Slow development server

Problem: Server takes long to start or respond.Solutions:

Optimize dependencies in vite.config.js:

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ['react', 'react-dom']
  }
})

Clear Vite cache:

rm -rf node_modules/.vite
npm run dev

Disable source maps for faster builds:

export default defineConfig({
  plugins: [react()],
  build: {
    sourcemap: false
  }
})

Component Rendering Issues

Images not loading

Problem: Product images show broken image icons.Diagnosis:

Check image URLs in browser DevTools Network tab
Verify API response contains valid imageUrl fields

Solutions:

Add error handling in ProductCard.jsx:

import { useState } from 'react';
import "./ProductCard.css";

export default function ProductCard({ title, price, image, badge }) {
  const [imgError, setImgError] = useState(false);
  const fallbackImage = "https://via.placeholder.com/300x200?text=No+Image";
  
  return (
    <div className="product-card">
      {badge && <div className="badge">{badge}</div>}
      
      <img 
        src={imgError ? fallbackImage : image} 
        alt={title}
        onError={() => setImgError(true)}
      />
      
      <div className="product-info">
        <h4>{title}</h4>
        <span>${price}</span>
      </div>
      
      <button className="product-btn">Ingredientes</button>
    </div>
  );
}

Check CORS for images: Some CDNs block cross-origin image requests
Verify image paths if using local assets:

import placeholderImg from '../../assets/placeholder.jpg';

Material Symbols icons not showing

Problem: Category icons appear as text or don’t render.Solution: Verify Material Symbols is loaded in index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Q-Sopa</title>
    
    <!-- Material Symbols -->
    <link rel="stylesheet" 
          href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Check in Categories.jsx usage:

<span className="material-symbols-outlined">{cat.icon}</span>

Mobile drawer not opening

Problem: Hamburger menu doesn’t open on mobile.Check these in src/components/Categories/Categories.jsx:

State is defined:

const [drawerOpen, setDrawerOpen] = useState(false);

Button click handler:

<button
  className="drawer-toggle"
  onClick={() => {
    console.log('Drawer toggled'); // Debug log
    setDrawerOpen(true);
  }}
  aria-label="Abrir menú de categorías"
>
  <span />
  <span />
  <span />
</button>

CSS classes are correct:

<nav className={`drawer-panel ${drawerOpen ? "open" : ""}`}>

Overlay closes drawer:

<div
  className={`drawer-overlay ${drawerOpen ? "open" : ""}`}
  onClick={() => setDrawerOpen(false)}
/>

Test on actual mobile device, not just browser resize (touch events may differ)

Categories not highlighting when active

Problem: Active category doesn’t show visual feedback.Solution: Verify state comparison in Categories.jsx:

const [active, setActive] = useState(null);

// Make sure ID types match (number vs string)
const handleClick = (id) => {
  console.log('Setting active:', id, typeof id);
  setActive(id);
  onCategoryChange?.(id);
};

// Render:
<button
  key={cat.id}
  className={`category-btn ${active === cat.id ? "active" : ""}`}
  onClick={() => handleClick(cat.id)}
>

If IDs don’t match (e.g., 1 vs "1"), convert them:

setActive(Number(id));

State Management Issues

State not updating

Problem: State changes don’t trigger re-renders.Common causes:

Mutating state directly:

// ❌ Wrong
products.push(newProduct);
setProducts(products);

// ✅ Correct
setProducts([...products, newProduct]);

Async setState:

// ❌ Won't work as expected
setProducts([]);
setLoading(false); // Might not reflect the state change

// ✅ Correct
setProducts([]);
setTimeout(() => setLoading(false), 0);

Missing dependencies in useEffect:

// ❌ Missing dependency
useEffect(() => {
  fetchProducts(categoryId);
}, []); // categoryId is missing

// ✅ Correct
useEffect(() => {
  fetchProducts(categoryId);
}, [categoryId]);

Infinite render loop

Problem: Component keeps re-rendering indefinitely.Cause: State update in render or missing useEffect dependencies.Solution:

// ❌ Wrong - causes infinite loop
function Menu() {
  const [data, setData] = useState([]);
  setData([...]); // Direct call in render
}

// ✅ Correct
function Menu() {
  const [data, setData] = useState([]);
  
  useEffect(() => {
    setData([...]);
  }, []); // Only run once
}

Check useEffect dependencies:

// ❌ Object causes re-render every time
const config = { key: 'value' };
useEffect(() => {
  // ...
}, [config]); // New object each render

// ✅ Use primitive values or useMemo
useEffect(() => {
  // ...
}, [config.key]);

Browser Compatibility

App not working in older browsers

Problem: Features don’t work in Safari, older Edge, etc.Solution: Check browser support and add polyfills if needed:

Check compatibility:

Optional chaining (?.) requires modern browsers
Promise.finally() needs polyfills for IE11

Target specific browsers in package.json:

{
  "browserslist": [
    "> 0.5%",
    "last 2 versions",
    "not dead",
    "not ie 11"
  ]
}

Use Vite’s legacy plugin for older browsers:

npm install --save-dev @vitejs/plugin-legacy

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  plugins: [
    react(),
    legacy({
      targets: ['defaults', 'not IE 11']
    })
  ]
})

Performance Issues

Slow loading / Large bundle size

Problem: Application takes long to load.Solutions:

Analyze bundle size:

npm run build
# Check the dist/ folder size

Implement code splitting:

import { lazy, Suspense } from 'react';

const Menu = lazy(() => import('./pages/Menu'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Menu />
    </Suspense>
  );
}

Optimize images:

Use WebP format
Compress images (TinyPNG, Squoosh)
Implement lazy loading

Enable compression on hosting platform (gzip/brotli)

Memory leaks

Problem: Application slows down over time.Solution: Clean up effects in Categories.jsx:

useEffect(() => {
  const handleKey = (e) => {
    if (e.key === "Escape") setDrawerOpen(false);
  };
  window.addEventListener("keydown", handleKey);
  
  // ✅ Cleanup function
  return () => window.removeEventListener("keydown", handleKey);
}, []);

Cancel fetch requests on unmount:

useEffect(() => {
  const controller = new AbortController();
  
  fetch(url, { signal: controller.signal })
    .then(data => setData(data))
    .catch(err => {
      if (err.name !== 'AbortError') {
        console.error(err);
      }
    });
  
  return () => controller.abort();
}, [url]);

Getting Help

If you’re still experiencing issues:

Check browser console for error messages
Review network requests in DevTools
Test API endpoints directly with curl or Postman
Verify environment variables are set correctly
Check package versions match the documentation

Enable detailed logging for debugging:

// src/services/api.js
const DEBUG = true;

export const getCategorias = async () => {
  if (DEBUG) console.log('Fetching categories from:', `${BASE_URL}/categories`);
  
  const res = await fetch(`${BASE_URL}/categories`);
  
  if (DEBUG) console.log('Response:', res.status, res.statusText);
  
  if (!res.ok) throw new Error("Error al cargar categorías");
  
  const data = await res.json();
  if (DEBUG) console.log('Categories data:', data);
  
  return data;
};

Building

Troubleshooting Guide

Overview

API Connection Issues

CORS Errors

1. Backend Configuration (Recommended)

2. Development Proxy

3. Verify Request Headers

Build Errors

Development Server Issues

Component Rendering Issues

State Management Issues

Browser Compatibility

Performance Issues

Getting Help

Next Steps

Customization

Deployment

Build docs developers (and LLMs) love

Building

​Overview

​API Connection Issues

​CORS Errors

​1. Backend Configuration (Recommended)

​2. Development Proxy

​3. Verify Request Headers

​Build Errors

​Development Server Issues

​Component Rendering Issues

​State Management Issues

​Browser Compatibility

​Performance Issues

​Getting Help

​Next Steps

Customization

Deployment

Build docs developers (and LLMs) love

Overview

API Connection Issues

CORS Errors

1. Backend Configuration (Recommended)

2. Development Proxy

3. Verify Request Headers

Build Errors

Development Server Issues

Component Rendering Issues

State Management Issues

Browser Compatibility

Performance Issues

Getting Help

Next Steps