Payroll Troubleshooting
Summary
Complete source-backed troubleshooting documentation for Payroll, including confirmed implementation, Transitional boundaries, unsupported capabilities, and safe operating guidance.
Audience
Payroll users, developers, QA and support engineers, architects, product owners, and implementation reviewers.
Overview
Scope and safety
This section provides safe diagnosis for authentication, tenant context, calculation, freeze, unfreeze, advance recovery, payslips, CSV/report export, bank export, projection freshness, outbox delay, notifications, gateway compatibility, database access, and migrations. It uses observable application behavior and source-confirmed boundaries; it does not prescribe direct data repair, secret disclosure, infrastructure commands, or destructive replay.
Start with the decision tree. Preserve the failed response category, correlation reference, tenant, period/run identifiers, selected native or compatibility route family, and timestamps. Redact employee, compensation, bank, government-identifier, and token data before escalation.
Scenario index
| Symptom family | First guide | Important boundary |
|---|---|---|
| Sign-in, unauthorized, wrong portal, or tenant failure | Authentication and tenant | UI access does not prove gateway/API authorization |
| Calculation rejected, empty, or inconsistent | Calculation failures | Attendance is required; other projections may be optional |
| Freeze/unfreeze or recovery failure | Freeze, unfreeze, and advance | Native and compatibility lifecycle behavior differs |
| Payslip, PDF, CSV/report, or bank export failure | Payslip and export | Native payslip/bank output requires frozen data |
| Attendance, leave, expense, or workforce data appears stale | Projection freshness | Payroll consumes local projections, not live upstream state |
| Event or notification appears delayed | Outbox and notification | Persisted intent does not prove relay or consumer delivery |
| Gateway mismatch, persistence, or migration issue | Gateway, database, and migrations | Do not repair by direct table edits |
Triage classifications
- Foundation: confirmed capability exists, but full operational automation is not established.
- Transitional: native and compatibility paths can return different lifecycle or error behavior.
- Requires confirmation: source does not establish ownership, delivery, authorization, or recovery behavior.
- Not implemented: do not troubleshoot the request as a hidden feature; examples include payment execution and accounting posting.
Documentation map
- Payroll Troubleshooting Decision Tree
- Payroll Authentication and Tenant Troubleshooting
- Payroll Calculation Failure Troubleshooting
- Payroll Freeze, Unfreeze, and Advance Troubleshooting
- Payroll Payslip and Export Troubleshooting
- Payroll Projection Freshness Troubleshooting
- Payroll Outbox and Notification Troubleshooting
- Payroll Gateway, Database, and Migration Troubleshooting
Resolution standard
A case is resolved only when the expected tenant-scoped state is observable through a supported read path, no duplicate mutation was introduced, and any required outbox/downstream result is independently verified. A successful retry alone is insufficient evidence. If the implementation cannot prove relay ownership, dependency health, or authorization enforcement, close the diagnostic step as Requires confirmation and escalate to the named service owner.
Source References
microservices/src/payroll-service/Program.csmicroservices/src/payroll-service/Application/PayrollCalculationService.csmicroservices/src/payroll-service/Messaging/PayrollReadModelConsumer.csmicroservices/src/payroll-service/Infrastructure/Persistence.csUI/salary-ui/apps/client-hrms-portal/src/App.tsxUI/salary-ui/apps/client-hrms-portal/src/components/AppLayout.tsxUI/salary-ui/apps/client-hrms-portal/src/utils/ProtectedRoute.tsxUI/salary-ui/apps/client-hrms-portal/src/pages/salary/CalculateSalaryPage.tsxmicroservices/src/payroll-service/Application/PayrollCompatService.csUI/salary-ui/apps/client-hrms-portal/src/pages/salary/AdvanceSalaryPage.tsxUI/salary-ui/apps/client-hrms-portal/src/pages/hr/PayrollFeaturePages.tsxmicroservices/src/payroll-service/Application/PayrollOutputsService.csmicroservices/src/payroll-service/Infrastructure/PayrollDbContext.csmicroservices/src/contracts/Events/PayrollCalculatedEvent.csmicroservices/src/contracts/Events/PayslipGeneratedEvent.csmicroservices/docs/payroll-cutover-runbook.mdmicroservices/scripts/compare-payroll-parity.ps1microservices/scripts/payroll-cutover-go-no-go.ps1microservices/scripts/smoke-payroll-cutover.ps1
Related Articles
See Also
Keywords
- Payroll troubleshooting
- Payroll module
Revision Information
- Status: Draft
- Last reviewed: 2026-07-15
- Review cycle: Quarterly