Troubleshooting

Overview

This guide covers common issues you may encounter and their solutions. For issues not covered here, check the application logs or contact support.

Installation Issues

Port Already in Use

Problem: Development server fails to start with “Port 5173 already in use” error. Solution:

Identify Process

Find what’s using the port:

# Linux/Mac
lsof -i :5173

# Windows
netstat -ano | findstr :5173

Kill Process

Stop the conflicting process or change the port in vite.config.ts:10:

server: {
  host: "::",
  port: 3000, // Use different port
}

Module Not Found Errors

Problem: Getting “Cannot find module” errors after installation. Solutions:

Clean Install
Clear Cache
Check Node Version

Remove and reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Clear package manager and Vite cache:

# Clear npm cache
npm cache clean --force

# Clear Vite cache
rm -rf .vite

# Reinstall
npm install

Ensure you’re using Node.js 18 or higher:

node --version
# Should show v18.x.x or higher

If not, update Node.js:

Use nvm (recommended)
Download from nodejs.org

TypeScript Errors

Problem: TypeScript compilation errors during build. Solutions:

Check TypeScript Version

Ensure TypeScript 5.8.3 or higher:

npx tsc --version

If version is wrong:

npm install -D [email protected]

Verify tsconfig.json

Check that tsconfig.json includes correct paths:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

IDE/Editor Issues

Restart your IDE/editor:

VS Code: Reload window (Ctrl+Shift+P → “Reload Window”)
Restart TypeScript server
Clear editor cache

Check for Type Errors

Run TypeScript compiler check:

npx tsc --noEmit

This shows all type errors without building.

Authentication Issues

Problem: Login fails with “Invalid credentials” error. Checklist:

Username and password are correct (case-sensitive)

Backend API is running and accessible

VITE_API_BASE_URL is configured correctly in .env

Network connection is stable

No CORS errors in browser console

Debug Steps:

Check API Connection

Open browser DevTools (F12) → Network tabLook for the login request:

Status should be 200 (success)
If 401: Wrong credentials
If 404: Wrong API URL
If 500: Backend error

Verify Environment Variable

Check that API URL is loaded:

console.log(import.meta.env.VITE_API_BASE_URL);

Should output your API URL, not undefined.

Test API Directly

Use curl to test authentication:

curl -X POST https://your-api.com/api/v1/auth/login \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json"

Registration Failed

Problem: Cannot register new user. Common Causes:

Email Not Whitelisted

Error: “Este correo no está autorizado para registrarse”Solution:

Contact system administrator to add email to whitelist
Check backend whitelist configuration
Verify email is spelled correctly

Weak Password

Error: “La contraseña debe tener al menos 8 caracteres”Solution:

Use password with minimum 8 characters
Include uppercase, lowercase, numbers, and symbols for stronger password
Check password strength indicator

Password Mismatch

Error: “Las contraseñas no coinciden”Solution:

Ensure “Password” and “Confirm Password” fields match exactly
Check for extra spaces or hidden characters

Username Already Exists

Error: Username is already takenSolution:

Choose a different username
Contact admin if you believe this is an error

Session Expired

Problem: Automatically logged out unexpectedly. Causes:

Idle timeout: 15 minutes of inactivity (src/components/auth/IdleHandler.tsx:21)
Browser closed: Session storage is cleared
Manual logout: User clicked logout

Solution:

Simply log in again
Stay active to prevent timeout
Consider implementing “remember me” feature

API Connection Issues

CORS Errors

Problem: Browser shows CORS policy errors in console.

Access to fetch at 'https://api.example.com' from origin 'http://localhost:5173' 
has been blocked by CORS policy

Solution: Configure CORS on your backend:

Express.js
Spring Boot
Nginx

const cors = require('cors');

app.use(cors({
  origin: 'http://localhost:5173',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Authorization', 'Content-Type']
}));

@Configuration
public class CorsConfig {
    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**")
                    .allowedOrigins("http://localhost:5173")
                    .allowedMethods("GET", "POST", "PUT", "DELETE")
                    .allowedHeaders("*")
                    .allowCredentials(true);
            }
        };
    }
}

location /api/ {
    add_header 'Access-Control-Allow-Origin' 'http://localhost:5173';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE';
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
    add_header 'Access-Control-Allow-Credentials' 'true';
    
    proxy_pass http://backend:8080;
}

Network Request Failed

Problem: All API requests fail with network error. Debug Checklist:

Check Backend Status

Verify backend server is running:

curl https://your-api.com/api/v1/health

Verify API URL

Check .env file:

cat .env
# Should show: VITE_API_BASE_URL=https://your-api.com/api/v1

Test Connectivity

Ping the server:

ping your-api.com

Check Firewall

Ensure firewall allows connections:

Backend port is open
No VPN blocking requests
Corporate firewall configured

Build Issues

Build Fails

Problem: Production build fails with errors. Solutions:

Out of Memory

Error: JavaScript heap out of memorySolution: Increase Node.js memory:

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

# Windows
set NODE_OPTIONS=--max-old-space-size=4096 && npm run build

ESLint Errors

Error: Build fails due to linting errorsSolution:

Fix linting errors:
```
npm run lint
```

Or temporarily disable linting in build:

package.json

"build": "vite build --mode production --no-lint"

Import Errors

Error: Cannot resolve module importsSolution:

Check import paths use @/ alias correctly
Verify files exist at import locations
Check file extensions (.tsx, .ts, .jsx, .js)
Ensure proper casing (case-sensitive)

Build Size Too Large

Problem: Bundle size exceeds recommended limits. Solutions:

Analyze Bundle

Use bundle analyzer:

npm install -D rollup-plugin-visualizer
npm run build

Add to vite.config.ts:

import { visualizer } from 'rollup-plugin-visualizer';

plugins: [
  react(),
  visualizer({ open: true })
]

Code Splitting

Use dynamic imports for large components:

const HeavyComponent = lazy(() => import('./HeavyComponent'));

Optimize Dependencies

Remove unused dependencies
Use lighter alternatives
Tree-shake properly

Runtime Issues

White Screen / App Won’t Load

Problem: Application shows blank screen. Debug Steps:

Check Browser Console

Open DevTools (F12) → Console tabLook for:

JavaScript errors
Failed network requests
Missing files (404 errors)

Verify Build

Check that dist/ folder contains:

index.html
assets/ folder with JS and CSS files

If missing, rebuild:

npm run build

Check Base Path

If deploying to subdirectory, configure base in vite.config.ts:

export default defineConfig({
  base: '/subdirectory/',
  // ...
})

Performance Issues

Problem: Application is slow or unresponsive. Optimization Checklist:

Enable production build (not development)

Minimize re-renders with React.memo

Use virtualization for long lists

Optimize images (compress, lazy load)

Enable code splitting

Cache API responses with TanStack Query

Profiling:

// Record performance profile
// DevTools → Performance → Record
// Perform slow action
// Stop recording and analyze

Data Issues

Data Not Updating

Problem: Changes don’t appear after saving. Checklist:

Check Network Request

Open DevTools → Network
Verify request was sent
Check response status (should be 200)
Confirm response data

Verify State Management

Check TanStack Query is invalidating cache
Confirm mutations are configured correctly
Look for stale data indicators

Force Refresh

Try hard refresh (Ctrl+Shift+R)
Clear browser cache
Check backend database directly

Export Not Working

Problem: Excel export fails or downloads empty file. Solutions:

Check File-Saver

Verify file-saver is installed:

npm list file-saver

If missing:

npm install file-saver @types/file-saver

Browser Compatibility

Ensure browser supports Blob API
Check pop-up blocker isn’t preventing download
Try different browser

Data Availability

Verify there’s data to export
Check date range filter
Confirm API returned data

Environment Issues

Environment Variables Not Loading

Problem: import.meta.env.VITE_API_BASE_URL returns undefined. Solutions:

Check File Name

File must be named exactly .env (with leading dot)

Verify Variable Prefix

All variables must start with VITE_:

# ✅ Correct
VITE_API_BASE_URL=https://api.com

# ❌ Wrong - won't be exposed to client
API_BASE_URL=https://api.com

Restart Dev Server

Environment changes require server restart:

# Stop server (Ctrl+C)
npm run dev

Check File Location

.env must be in project root (same level as package.json)

Getting Help

Debugging Tools

Browser DevTools:

Console: View errors and logs
Network: Monitor API requests
Application: Check storage (sessionStorage)
Sources: Debug JavaScript
Performance: Profile slow operations

React DevTools:

Component inspection
Props and state viewing
Performance profiling
Hook debugging

Log Files

Check logs for errors: Development:

Browser console
Terminal running npm run dev

Production:

Server logs
Error monitoring service (Sentry, etc.)
Browser console (if accessible)

Common Error Messages

Failed to fetch

Cause: Network request failedCheck:

Backend is running
API URL is correct
CORS is configured
Network connectivity

Cannot read property of undefined

Cause: Accessing property on undefined/null objectCheck:

Optional chaining: user?.name
Null checks before access
API response structure
Loading states

Unexpected token

Cause: Syntax error in JavaScript/JSONCheck:

Missing/extra commas
Unclosed brackets/braces
Invalid JSON in API response
File encoding (should be UTF-8)

Support Resources

Installation Guide

Review installation steps

Configuration

Check configuration settings

Environment Setup

Verify environment variables

User Management

Authentication troubleshooting

If your issue isn’t covered here, check the browser console for specific error messages and review the relevant documentation sections.

Setup

Operations

Overview

Installation Issues

Port Already in Use

Module Not Found Errors

TypeScript Errors

Authentication Issues

Registration Failed

Session Expired

API Connection Issues

CORS Errors

Network Request Failed

Build Issues

Build Fails

Build Size Too Large

Runtime Issues

White Screen / App Won’t Load

Performance Issues

Data Issues

Data Not Updating

Export Not Working

Environment Issues

Environment Variables Not Loading

Getting Help

Debugging Tools

Log Files

Common Error Messages

Support Resources

Installation Guide

Configuration

Environment Setup

User Management

Build docs developers (and LLMs) love

Setup

Operations

​Overview

​Installation Issues

​Port Already in Use

​Module Not Found Errors

​TypeScript Errors

​Authentication Issues

​Unable to Login

​Registration Failed

​Session Expired

​API Connection Issues

​CORS Errors

​Network Request Failed

​Build Issues

​Build Fails

​Build Size Too Large

​Runtime Issues

​White Screen / App Won’t Load

​Performance Issues

​Data Issues

​Data Not Updating

​Export Not Working

​Environment Issues

​Environment Variables Not Loading

​Getting Help

​Debugging Tools

​Log Files

​Common Error Messages

​Support Resources

Installation Guide

Configuration

Environment Setup

User Management

Build docs developers (and LLMs) love

Overview

Installation Issues

Port Already in Use

Module Not Found Errors

TypeScript Errors

Authentication Issues

Unable to Login

Registration Failed

Session Expired

API Connection Issues

CORS Errors

Network Request Failed

Build Issues

Build Fails

Build Size Too Large

Runtime Issues

White Screen / App Won’t Load

Performance Issues

Data Issues

Data Not Updating

Export Not Working

Environment Issues

Environment Variables Not Loading

Getting Help

Debugging Tools

Log Files

Common Error Messages

Support Resources