Employee troubleshooting
Goal
Resolve common employee create/update and related HR errors.
Who it is for
HR clerk / admin diagnosing 422 responses from employee and time APIs.
Preconditions
- Access to the failing screen and enough permission to see the error message.
Symptoms and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| “This party is already an employee.” | hr.party_already_employee | Open the existing employee; do not re-link the same party. |
| “An employee with number … already exists.” | hr.duplicate_employee_number | Pick another number or enable auto-numbering in setup. |
| Number required / blank | Auto-number off | Enter a number or turn on Auto-assign employee numbers. |
| “An employee cannot be their own manager.” | hr.invalid_manager | Choose a different Reports to. |
| Unknown department / party | Inactive or wrong id | Pick an active department / existing party. |
| Cannot log billable time | Terminated employee | hr.terminated_cannot_log_time — use an active employee. |
| Employee missing after archive | Soft archive | Archived employees are hidden (404); do not expect them on Active filter. |
| Module 422 on related tab | Module not enabled | Enable attendance, leave_management, compensation, benefits, or payroll_integration as needed. |
| Department delete blocked | Employees still assigned | hr.department_has_employees — reassign first. |
Result
You can correct master data or permissions and retry without creating duplicate people records.