Skip to main content

Troubleshooting

Backend Issues​

"SQLSTATE: Connection refused" when starting the API​

Cause: PostgreSQL is not running or the connection config is wrong.

Fix:

  1. Ensure PostgreSQL is running (check Laragon or system services).
  2. Verify .env database credentials: 
    DB_CONNECTION=pgsql
    DB_HOST=127.0.0.1
    DB_PORT=5432
    DB_DATABASE=hrms
    DB_USERNAME=postgres
    DB_PASSWORD=your_password
  3. Test the connection: php artisan db:monitor

"Class not found" or autoload errors​

Fix:

composer dump-autoload
php artisan clear-compiled

Migrations fail with "relation already exists"​

Cause: Database already has tables from a previous run.

Fix: Reset the database (development only):

php artisan migrate:fresh --seed
warning

This drops all tables and recreates them. Never run this in production.

CORS errors when frontend calls the API​

Cause: The frontend URL is not in the allowed origins.

Fix: Check config/cors.php and .env:

FRONTEND_URL=http://localhost:3000
SANCTUM_STATEFUL_DOMAINS=localhost:3000
SESSION_DOMAIN=localhost

419 "CSRF token mismatch"​

Cause: The frontend is not sending the XSRF-TOKEN cookie or not hitting /sanctum/csrf-cookie first.

Fix:

  1. Ensure the frontend calls GET /sanctum/csrf-cookie before login.
  2. Check that SESSION_DOMAIN in .env matches the frontend domain.
  3. Verify SANCTUM_STATEFUL_DOMAINS includes the frontend host:port.
  4. Ensure cookies are being sent with credentials: 'include'.

403 "This action is unauthorized"​

Cause: The logged-in user doesn't have the required permission.

Fix:

  1. Check the user's role: php artisan tinker → User::find(1)->roles
  2. Check role permissions: Role::findByName('HR')->permissions->pluck('name')
  3. If needed, assign permissions via the Roles UI or Tinker.

File uploads fail with "too large"​

Cause: PHP or web server limits are too low.

Fix: Update php.ini:

upload_max_filesize = 10M
post_max_size = 12M

Restart the web server after changes.

Frontend Issues​

Blank page after login​

Cause: API URL mismatch or CORS issue.

Fix:

  1. Check .env.local in the frontend: 
    NEXT_PUBLIC_API_URL=http://localhost:8000
  2. Check browser console for CORS or network errors.
  3. Ensure the backend is running on the expected port.

"Network Error" or "Failed to fetch"​

Cause: Backend is not running, or wrong API URL.

Fix:

  1. Verify the backend is running: curl http://localhost:8000/api/user
  2. Check that NEXT_PUBLIC_API_URL is correct.
  3. Check for proxy or firewall issues.

Styles look broken or missing​

Fix:

npm run dev

If still broken, clear the Next.js cache:

rm -rf .next
npm run dev

TypeScript errors after pulling new code​

Fix:

npm install
npx tsc --noEmit

Email / Notification Issues​

Emails not being sent​

Cause: Mail server not configured or not running.

Fix for development:

  1. Install smtp4dev
  2. Run it: smtp4dev
  3. Configure .env: 
    MAIL_MAILER=smtp
    MAIL_HOST=localhost
    MAIL_PORT=2525
  4. Open smtp4dev UI at http://localhost:5000 to see captured emails.

Notifications not appearing in-app​

Fix:

  1. Check that the notification event is enabled in Notification Settings.
  2. Verify the notifications table has records: php artisan tinker → Notification::count()
  3. Check browser console for API errors on the notifications endpoint.

Database Issues​

Seeder fails with duplicate key​

Cause: Running seeder on a database that already has data.

Fix:

php artisan migrate:fresh --seed

Slow queries​

Fix:

  1. Enable query logging: Check storage/logs/laravel.log
  2. Add database indexes for frequently filtered columns
  3. Check for N+1 queries using Laravel Telescope or debug bar

General Tips​

  • Always check storage/logs/laravel.log for backend errors.
  • Use browser Developer Tools (F12) → Network tab to inspect API calls.
  • Run php artisan config:clear after changing .env values.
  • Run php artisan cache:clear after configuration changes.
  • Use php artisan tinker for quick database queries and debugging.