Troubleshooting

Installation Issues

Blank page after setup

Ensure your web server's document root points to the public/ directory. Check that PHP 8.2+ and required extensions (PDO, mbstring, XML, JSON, cURL) are installed.

Migration fails with SQL error

Verify MySQL is running and the credentials in .env are correct. The database must exist before running migrations:

php artisan migrate --force

Frontend shows unstyled HTML

The Vite build may not have completed. Run:

npm run build

Device Issues

Device not recording attendance

Check the following:

1. The device is registered and Active in Operations > Devices. 2. The device_token in the request matches the token shown in the device list. 3. The guard's biometric enrollment is Active and uses the correct identifier. 4. The device can reach the server (no firewall blocking the outbound HTTP call).

"No matching biometric record found"

The biometric_type + identifier combination sent by the device does not match any enrolled guard_biometric record. Verify the identifier is entered exactly as the device provides it (case-sensitive).

"Invalid device token"

The token sent in the request body does not match any registered device. Regenerate the token from the devices list and update the device configuration.

Attendance Issues

Duplicate attendance records

The system uses a unique constraint on (guard_id, date). Saving the same guard and date overwrites the existing record rather than creating a duplicate.

Salary showing zero

Ensure the guard has a basic_salary value set and attendance records exist for the selected month.