CloudPOS Documentation

# Troubleshooting

Common issues and solutions for CloudPOS setup and operation.

# Quick Diagnosis

# Check Services Are Running

# Check API server
curl http://localhost:3000/api

# Check frontend
curl http://localhost:5173

# Check MySQL
mysql -u root -p -e "SELECT 1"

# Check Logs

# PM2 logs (production)
pm2 logs cloudpos

# Server logs
tail -f logs/pm2-error.log
tail -f logs/pm2-out.log

# Nginx logs
sudo tail -f /var/log/nginx/error.log

# Common Issues

# Build Errors

# Error: Cannot find module or Module not found

Cause: Dependencies not installed

Solution:

# Install root dependencies
npm install

# Install server dependencies
cd server && npm install

# Install client dependencies
cd ../client && npm install

# Error: TypeScript errors or Type errors

Cause: TypeScript compilation errors

Solution:

# Check TypeScript version
npm list typescript

# Reinstall TypeScript
npm install typescript@latest --save-dev

# Clean and rebuild
cd server && npm run build
cd ../client && npm run build

# Error: Prisma Client not generated

Cause: Prisma Client missing

Solution:

cd server
npm run prisma:generate

# Blank Page / White Screen

# Frontend shows blank page

Cause: JavaScript errors or API connection issues

Solutions:

  1. Check browser console:

    • Open DevTools (F12)
    • Check Console tab for errors
    • Check Network tab for failed requests

  2. Verify API is running:

    curl http://localhost:3000/api

  3. Check CORS settings:

    CORS_ORIGIN=http://localhost:5173

  4. Clear browser cache:

    • Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
    • Or clear cache in browser settings

  5. Check build output:

    cd client
npm run build
# Check for build errors

# Admin panel blank

Cause: Admin routes not loading

Solutions:

  1. Check URL:

    • Should be: http://localhost:5173/admin/login
    • Not: http://localhost:5173/admin (missing /login)

  2. Check admin user exists:

    cd server
npx ts-node prisma/create-admin.ts

  3. Check API response:

    curl http://localhost:3000/api/admin/auth/me

# 404 API Errors

# Error: 404 Not Found for API endpoints

Cause: API route doesn't exist or server not running

Solutions:

  1. Check API server is running:

    # Should return response
curl http://localhost:3000/api

  2. Check route exists:

    • Verify endpoint URL is correct
    • Check API documentation

  3. Check API prefix:

    • All routes should start with /api
    • Example: /api/auth/login not /auth/login

  4. Check server logs:

    pm2 logs cloudpos

# CORS Errors

# Error: CORS policy: No 'Access-Control-Allow-Origin' header

Cause: CORS not configured correctly

Solutions:

  1. Check CORS_ORIGIN in .env:

    CORS_ORIGIN=http://localhost:5173
# Must match frontend URL exactly (with http://)

  2. Restart API server:

    # Development: Stop and restart
# Production: pm2 restart cloudpos

  3. Check for typos:

    • No trailing slash
    • Include protocol (http:// or https://)
    • Match port number

# Database Connection Errors

# Error: Can't reach database server or ECONNREFUSED

Cause: MySQL not running or wrong credentials

Solutions:

  1. Check MySQL is running:

    # Windows (Laragon)
# Check Laragon dashboard

# macOS
brew services list

# Linux
sudo systemctl status mysql

  2. Start MySQL:

    # macOS
brew services start mysql@8.0

# Linux
sudo systemctl start mysql

  3. Test connection:

    mysql -u root -p -h localhost

  4. Check DATABASE_URL in .env:

    DATABASE_URL="mysql://user:password@localhost:3306/cloudpos"

# Error: Access denied for user

Cause: Wrong username/password or user doesn't exist

Solutions:

  1. Verify credentials:

    • Check username and password in DATABASE_URL
    • Test with: mysql -u USER -p

  2. Create database user:

    CREATE USER 'cloudpos'@'localhost' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON cloudpos.* TO 'cloudpos'@'localhost';
FLUSH PRIVILEGES;

  3. Check user privileges:

    SHOW GRANTS FOR 'cloudpos'@'localhost';

# Migration Errors

# Error: Migration failed or Table already exists

Cause: Database state mismatch

Solutions:

  1. Reset database (⚠️ deletes all data):

    cd server
npx prisma migrate reset
npm run prisma:migrate

  2. Push schema without migrations:

    npm run prisma:db:push

  3. Check existing tables:

    USE cloudpos;
SHOW TABLES;

# Payment / Subscription Issues

# Payment succeeds but plan not assigned

Cause: Webhook not configured or failing

Solutions:

  1. Check webhook configuration:

    • Stripe Dashboard → Webhooks
    • Verify endpoint URL is correct
    • Check webhook secret matches

  2. Check webhook events:

    • Stripe Dashboard → Webhooks → Select webhook → Events
    • Look for failed events
    • Check error messages

  3. Manually assign plan:

    • Admin Panel → Tenants → Select tenant
    • Manually assign plan

  4. Check application logs:

    pm2 logs cloudpos | grep -i webhook

# Stripe webhook not receiving events

Cause: Webhook URL not accessible or misconfigured

Solutions:

  1. Verify webhook URL:

    • Must be publicly accessible (not localhost in production)
    • Must use HTTPS in production
    • Must be: https://yourdomain.com/api/subscriptions/webhook

  2. Test webhook:

    • Stripe Dashboard → Webhooks → Send test webhook
    • Check if received

  3. Check firewall:

    • Allow Stripe IPs
    • Check server firewall rules

Cause: Initial data fetch failing or slow

Solutions:

  1. Check API response:

    curl http://localhost:3000/api/users/profile

  2. Check browser console:

    • Look for failed API requests
    • Check for CORS errors

  3. Clear cache and refresh:

    • Hard refresh: Ctrl+Shift+R

# Toast Notifications Not Appearing

Cause: Toast library not initialized or CSS missing

Solutions:

  1. Check toast library installed:

    cd client
npm list react-hot-toast

  2. Check toast container in HTML:

    • Should have <Toaster /> component in root

  3. Check CSS imports:

    • Verify toast CSS is imported

# Google Login Issues

Cause: Firebase/Google credentials not configured

Solutions:

  1. Check Firebase configuration:

    • Admin Panel → Settings → System Settings
    • Verify Firebase credentials are set

  2. Check Google OAuth setup:

    • Google Cloud Console → APIs & Services → Credentials
    • Verify OAuth client ID is configured

  3. Check allowed domains:

    • Add your domain to authorized domains in Google Console

# Missing Images / Uploads Not Loading

Cause: Upload directory not accessible or wrong path

Solutions:

  1. Check upload directory exists:

    ls -la server/uploads

  2. Check file permissions:

    chmod -R 775 server/uploads

  3. Check Nginx config (production):

    location /uploads {
    alias /var/www/cloudpos/server/uploads;
}

  4. Check upload path in code:

    • Verify upload path matches server configuration

# Permission Issues

# Error: Missing required permission

Cause: User doesn't have required permissions

Solutions:

  1. Check user roles:

    • Admin Panel → Users → Select user
    • Verify roles are assigned

  2. Check role permissions:

    • Admin Panel → Roles → Select role
    • Verify permissions are assigned

  3. Assign permissions:

    • Admin Panel → Roles → Edit role
    • Add required permissions

# Getting More Help

# Check Logs

Application logs:

# PM2 logs
pm2 logs cloudpos --lines 100

# Server error log
tail -f logs/pm2-error.log

# Server output log
tail -f logs/pm2-out.log

Database logs:

# MySQL error log
sudo tail -f /var/log/mysql/error.log

Nginx logs:

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

# Access log
sudo tail -f /var/log/nginx/access.log

# Enable Debug Mode

Development:

NODE_ENV=development

Check verbose logs:

  • Server logs show more details in development mode
  • Browser console shows more errors

# Common Commands

# Restart everything
pm2 restart cloudpos
sudo systemctl restart nginx

# Check service status
pm2 status
sudo systemctl status nginx
sudo systemctl status mysql

# Test database connection
mysql -u root -p -e "SELECT 1"

# Test API
curl http://localhost:3000/api

# Rebuild everything
cd server && npm run build
cd ../client && npm run build

Still stuck? Review the Production Checklist for a complete setup verification.

← Production Checklist →