Troubleshooting Guide

Common Issues

Application Won't Start

Symptoms: Container fails to start or crashes immediately

Solutions:

1. Check Docker logs: docker compose logs lager-guru
2. Verify environment variables in .env
3. Check port availability: netstat -tulpn | grep 80
4. Verify Docker daemon: docker ps

Database Connection Errors

Symptoms: "Failed to connect to Supabase" or authentication errors

Solutions:

1. Verify VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY in .env
2. Check Supabase project status
3. Verify network connectivity
4. Check RLS policies allow access

Real-time Updates Not Working

Symptoms: Changes don't appear without refresh

Solutions:

1. Check Supabase Realtime is enabled
2. Verify WebSocket connection in browser console
3. Check RLS policies allow SELECT
4. Verify subscription channels are correct

Barcode Scanner Not Working

Symptoms: Camera doesn't open or scanning fails

Solutions:

1. Verify HTTPS is enabled (required for camera access)
2. Check browser permissions for camera
3. Test on different device/browser
4. Check console for errors

GPS Tracking Not Working

Symptoms: Driver locations not updating

Solutions:

1. Verify location permissions granted
2. Check HTTPS is enabled
3. Verify driver_locations table exists
4. Check RLS policies for driver_locations

Build Failures

Symptoms: npm run build fails

Solutions:

1. Clear node_modules: rm -rf node_modules && npm install
2. Check TypeScript errors: npx tsc --noEmit
3. Verify all dependencies installed
4. Check for syntax errors

Performance Issues

Symptoms: Slow page loads or laggy UI

Solutions:

1. Check network tab for slow requests
2. Verify database queries are optimized
3. Check for memory leaks
4. Review RLS policy performance
5. Enable service worker caching

Error Messages

"useAuth must be used within an AuthProvider"

Cause: Component using useAuth outside of AuthProvider

Solution: Wrap component tree with AuthProvider

"Row-level security policy violation"

Cause: RLS policy blocking access

Solution:

1. Check user role
2. Verify RLS policy conditions
3. Check table permissions

"Failed to fetch"

Cause: Network error or CORS issue

Solution:

1. Check network connectivity
2. Verify Supabase URL is correct
3. Check CORS settings in Supabase
4. Verify API endpoint exists

Debugging Tips

Enable Debug Logging

Add to browser console:

localStorage.setItem('debug', 'true')

Check Supabase Connection

import { supabase } from '@/integrations/supabase/client'
const { data, error } = await supabase.from('shipments').select('*').limit(1)
console.log('Connection test:', { data, error })

Monitor Realtime Subscriptions

const channel = supabase.channel('test')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'shipments' }, 
    (payload) => console.log('Realtime event:', payload)
  )
  .subscribe()

Check Service Worker

navigator.serviceWorker.getRegistrations().then(registrations => {
  console.log('Service Workers:', registrations)
})

Getting Help

Check Logs

Docker logs:

docker compose logs -f lager-guru

Nginx logs:

sudo tail -f /var/log/nginx/error.log

Browser console: Open DevTools (F12)

Resources

• Runbook - Operational procedures
• Maintenance Guide - Maintenance checklist
• GitHub Issues

Prevention

Best Practices

1. Test before deploying - Verify changes locally
2. Monitor health endpoint - Set up alerts
3. Regular backups - Schedule database backups
4. Update dependencies - Keep packages current
5. Review logs - Check logs regularly

Monitoring

Set up monitoring for:

• Application health
• Database performance
• Error rates
• Response times
• Resource usage