Skip to main content

Troubleshooting

Common issues and solutions for WorkForce installation and operation.

Installation Issues​

npm install fails​

Symptoms: Errors during dependency installation.

Solutions:

  1. Clear npm cache: npm cache clean --force
  2. Delete node_modules and package-lock.json, then retry
  3. Ensure Node.js version is 18.17+: node --version
  4. On Windows, run terminal as Administrator

prisma migrate fails​

Symptoms: Migration errors or connection refused.

Solutions:

  1. Verify PostgreSQL is running: pg_isready
  2. Check DATABASE_URL in .env — ensure host, port, user, password, and database are correct
  3. Test connection: psql -h localhost -U workforce -d workforce
  4. Ensure the database exists and the user has permissions

Build fails with memory error​

Symptoms: JavaScript heap out of memory

Solution:

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

On PowerShell:

$env:NODE_OPTIONS = "--max-old-space-size=4096"
npm run build

Runtime Issues​

Application won't start​

Check these in order:

  1. .env file exists and has all required variables
  2. npx prisma generate has been run
  3. npm run build completed successfully (production)
  4. Port is not in use: netstat -ano | findstr :3000

"Invalid NEXTAUTH_URL"​

Ensure NEXTAUTH_URL in .env matches the URL you access the app from:

  • Development: http://localhost:3000
  • Production: https://your-domain.com

Database connection errors​

Symptoms: "Connection refused" or "Authentication failed"

  1. Verify PostgreSQL is running
  2. Check firewall rules allow connection on port 5432
  3. Verify credentials in DATABASE_URL
  4. For remote databases, ensure pg_hba.conf allows your IP

Attendance Issues​

Check-in location not detected​

  1. User must grant Location permission to the app
  2. GPS must be enabled on the device
  3. Check if office locations are configured (Administration → Office Locations)
  4. Verify the office location radius is large enough

Check-in marked as Late incorrectly​

  1. Verify the employee's assigned shift and start time
  2. Check the configured grace period
  3. Verify the server time zone matches your organization's time zone

Approval Issues​

Requests not appearing for approver​

  1. Check if a workflow is configured for the request type
  2. Verify the approver is assigned in the workflow stage
  3. If no workflow exists, verify the employee has a department with a manager
  4. HR users should see all pending requests — verify the user's role is set to hr

Stuck requests​

If a request is stuck in "pending" or "in_review":

  1. Check if the assigned approver's account is active
  2. Verify workflow stages are complete and correct
  3. As admin/HR, you can manually update the request status

Mobile App Issues​

App crashes on launch​

  1. Ensure the app is on the latest version
  2. Clear app data/cache
  3. Uninstall and reinstall
  4. Check that the server URL is correct and reachable

Push notifications not received​

  1. Check notification permission in Profile → Permissions
  2. On Android: verify the notification channel is enabled in device settings
  3. Check battery optimization isn't killing the app
  4. Verify the server has push notification services configured

OTA update fails​

  1. Check internet connection
  2. Restart the app and try again
  3. If update repeatedly fails, uninstall and reinstall the app

Getting Help​

If you can't resolve the issue:

  1. Check the application logs (logs/ directory or PM2/NSSM logs)
  2. Check the browser developer console for JavaScript errors
  3. Contact your system administrator with the error details