Troubleshooting Guide
Common issues — symptom, cause, actions, escalation.
---
Cannot log in
| Symptom | Invalid credentials or redirect loop |
| Likely cause | Wrong password; no account; session/CSRF issue |
| User action | Reset via /forgot-password if SMTP on |
| Admin action | Verify user exists; re-send invite |
| Escalate | SMTP misconfiguration; operator password reset |
---
Invitation does not work
| Symptom | Link expired or invalid token |
| Likely cause | Revoked invite; email typo; token consumed |
| User action | Request new invite from admin |
| Admin action | Create new invite at /hrms/invites; share manual URL if no email |
| Escalate | Token generation bug |
---
Employee cannot see data
| Symptom | Empty HRMS after login |
| Likely cause | No org membership; wrong role; invite not accepted |
| User action | Accept invite; use People Hub not Career only |
| Admin action | Link user to org; assign employee role |
| Escalate | Tenant membership missing in DB |
---
Manager cannot see team member
| Symptom | Direct report missing on /hrms/manager/team |
| Likely cause | manager_id / manager_email not set |
| Admin action | Edit employee manager; re-import manager pass |
| Escalate | Import ordering issue — fix manager row first |
---
Leave balance unexpected
| Symptom | Balance too high/low |
| Likely cause | Pro-rata hire date; missing opening balance; unapproved leave |
| Admin action | Check policy, hire date, opening_balance_days; approved requests |
| Escalate | Engine bug — capture employee ID and dates |
---
Holiday calendar incorrect
| Symptom | Wrong holidays |
| Likely cause | Calendar shell without dates; wrong calendar code on employee |
| Admin action | Add dates manually; fix holiday_calendar_code |
| Escalate | No auto holiday API — expected limitation |
---
Application not visible
| Symptom | Recruiter cannot find application |
| Likely cause | Wrong org; filtered inbox; applied to different careers slug |
| Recruiter action | Search pipeline by candidate email |
| Escalate | Cross-tenant data issue — operator |
---
Interview slot issue
| Symptom | Candidate cannot select slot |
| Likely cause | No slots created; expired options |
| Recruiter action | Add new slots on application |
| Escalate | UI/state bug |
---
Document not visible
| Symptom | Employee expects payslip/contract |
| Likely cause | Feature not available — no employee document store |
| Admin action | Explain limitation; use external DMS |
| Escalate | N/A unless resume on application (recruiting only) |
---
Worker job delayed
| Symptom | External apply stuck |
| Likely cause | Worker not running; site blocking automation |
| User action | Apply manually; check /applications |
| Escalate | Operator runs queue drain / worker health |
---
Import validation error
| Symptom | Validate fails |
| Likely cause | Bad date; unknown department; duplicate email |
| Admin action | Fix CSV; download template again |
| Escalate | Persistent false positive — file bug report |
---
Duplicate employee warning
| Symptom | Duplicate email in preview |
| Likely cause | Row in file or existing employee |
| Admin action | Use create_or_update with external_employee_id or remove duplicate |
| Escalate | — |
---
Company configuration incomplete
| Symptom | Onboarding checklist blocks progress |
| Likely cause | Country not set; policy missing |
| Admin action | Complete /hrms/onboarding and setup guide order |
| Escalate | — |
---
Help: /help/troubleshooting