TalinoHR

Troubleshooting Common Issues

8 min read

This guide covers frequently encountered issues in TalinoHR and how to resolve them.

Payroll Issues

Payroll Won't Compute

Symptoms: Clicking "Compute" on a payroll run produces an error or no results.

Check these:

  1. Payroll run status: Only DRAFT status payroll runs can be computed. If the status is COMPUTED, REVIEWED, APPROVED, or DISBURSED, you cannot recompute without first resetting to DRAFT (if applicable).
  2. Employee status: Only active employees are included. Employees with status RESIGNED, TERMINATED, or RETIRED are excluded unless they separated within the payroll period (for prorated pay).
  3. Employee count: If the payroll run has a location filter (locationId), only employees assigned to that work location are included. Check that employees have the correct workLocationId.
  4. Period dates: Verify the period start and end dates are correct and don't overlap with existing computed payroll runs for the same period and location.
  5. Suspended employees: Employees under active disciplinary suspension during the payroll period are automatically skipped (no pay during suspension).

Payroll Shows Wrong Net Pay

Check these:

  1. Attendance data: Verify attendance records exist for the payroll period. Missing attendance records mean no deductions for absences/lates but also no overtime/NSD.
  2. Pay basis: Check the employee's pay basis (MONTHLY, DAILY, HOURLY). The basic pay calculation differs significantly based on this setting.
  3. Work schedule: If the employee has a work schedule assigned, the daily rate and monthly rate are derived from schedule parameters (work days/week, hours/day). An incorrect schedule can affect rates.
  4. Allowances: Check if allowances are set up correctly. Non-taxable vs. taxable allowances affect withholding tax.
  5. Loan deductions: Active loans are automatically deducted. Check the Loans page if deductions seem too high.

Payroll Adjustment Not Appearing

Check these:

  1. Adjustment status: Only PENDING adjustments are consumed by the payroll engine. If the adjustment was already APPLIED to a previous run, it won't be picked up again.
  2. Payroll run status: Adjustments are only consumed when the payroll is computed (status moves from DRAFT to COMPUTED).
  3. Employee match: Verify the adjustment is linked to the correct employee ID.

Leave Balance Issues

Leave Balance Shows Wrong Number

Understanding the balance formula: LeaveBalance.balance = credits - used - pending

The balance field already excludes both used (consumed) days and pending (awaiting approval) days.

Check these:

  1. Credits: Verify the total credits allocated for the leave type. Navigate to Time & Leave → Leave Balances (/leaves/balances) and check the credits field.
  2. Used days: Check how many days have been consumed (approved and taken leave applications).
  3. Pending days: Pending leave applications reduce the available balance. If a pending request is later rejected, the balance is restored.
  4. Leave type eligibility: Some leave types have eligibility rules based on gender, solo parent status, or tenure. An employee may not be eligible for certain leave types.
  5. Annual reset: Leave balances may need to be reset at the start of each year. Check if balances were carried over or re-initialized.

Employee Can't File Leave

Check these:

  1. Insufficient balance: The employee's available balance for the selected leave type must be greater than or equal to the requested days.
  2. Leave type not assigned: The employee must have a LeaveBalance record for the leave type. Check if the leave balance was created during onboarding.
  3. Overlapping dates: The system may reject leave requests that overlap with existing approved or pending leave applications.

Attendance Issues

Attendance Not Recording

Check these:

  1. Work schedule assignment: The absence detection system requires a work schedule to be assigned to the employee. Without a schedule, the system cannot determine which days are work days vs. rest days.
  2. Schedule configuration: Verify the work schedule has correct time-in/time-out for each working day. Days with no time-in are treated as rest days.
  3. Date range: Attendance records are date-specific. Check that you're looking at the correct date range.
  4. Payroll lock: Once a payroll run is computed for a period, attendance records for those dates are locked and cannot be modified.

Employee Marked Absent Incorrectly

Check these:

  1. Rest day vs. work day: Verify the employee's work schedule. If the day in question has no time-in scheduled, it's a rest day and should not generate an absence record.
  2. Holiday: Check if the date is a holiday. Holidays should not generate absence records.
  3. Leave on file: If the employee has an approved leave for that date, the attendance record should show isOnLeave: true instead of isAbsent: true.
  4. Attendance record timing: The absence detection runs for a date range. If it ran before the employee clocked in, an absence may have been created prematurely.

Overtime Issues

Overtime Not Reflecting in Payroll

Key fact: The payroll engine reads OvertimeApplication records directly, not AttendanceRecord.overtimeMinutes. The overtime minutes field on attendance records is for display only.

Check these:

  1. OT approval status: Only APPROVED overtime applications are included in payroll. Verify the OT request status is APPROVED (not PENDING or REJECTED).
  2. OT date within period: The OT application date must fall within the payroll period (between periodStart and periodEnd).
  3. Payroll computed after approval: If the payroll was computed before the OT was approved, the OT won't be included. Recompute the payroll after approving the OT.
  4. Employee match: Verify the OT application is for the correct employee.

OT Amount Seems Wrong

Check these:

  1. Day type: The OT multiplier depends on the day type (ordinary 1.25x, rest day 1.69x, holiday up to 3.38x). Verify the correct day type was detected.
  2. Hourly rate: OT pay uses the employee's hourly rate. Check if the hourly rate is correctly derived from the pay basis and work schedule.
  3. Hours: Verify the number of OT hours filed matches what was expected.

Payslip Issues

Payslip PIN Not Working

Check these:

  1. PIN set: Verify the employee has a payslipPin value set in their record. If null, the employee cannot access payslips.
  2. PIN format: The payslip password scheme is configured via ComplianceSetting key payslip-password-scheme. Default is LASTNAME_BIRTHDATE (e.g., "DELA CRUZ19900115"). Verify the employee is entering the correct format.
  3. PIN hash: The PIN is stored as a bcrypt hash. If the employee forgot their PIN, it must be reset by an admin.
  4. Case sensitivity: Check if the scheme uses uppercase or the exact format expected.

Payslip Shows No Data

Check these:

  1. Payroll run status: Payslips are generated from PayrollItem records. The payroll run must be at least COMPUTED status.
  2. Employee included: Verify the employee was included in the payroll run (not excluded by location filter or inactive status).
  3. Pay frequency match: Check that the employee is on the correct pay frequency (SEMI_MONTHLY or MONTHLY).

Report Issues

Reports Showing Wrong Data

Check these:

  1. Date range filters: The most common reporting issue is selecting the wrong year or month. Double-check the year and month parameters.
  2. Payroll run status: Reports aggregate data from PayrollItem records. Ensure all relevant payroll runs are in COMPUTED, APPROVED, or DISBURSED status.
  3. Run types included: Annual reports (BIR 2316, Alphalist) aggregate REGULAR, THIRTEENTH_MONTH, and ANNUALIZATION run types. Make sure all applicable runs have been processed.
  4. Location filter: If payroll runs were location-scoped, reports should include all locations for complete data.

BIR 2316 / Alphalist Missing Employees

Check these:

  1. No payroll items: Employees with no PayrollItem records for the year won't appear. Check if they were included in payroll runs.
  2. Run type: Only REGULAR, THIRTEENTH_MONTH, and ANNUALIZATION run types are included. LEAVE_MONETIZATION and FINAL_PAY runs are separate.
  3. Year parameter: Verify you selected the correct year.

General Tips

  • Clear browser cache: If the UI seems stuck or showing stale data, clear the browser cache or do a hard refresh (Ctrl+Shift+R).
  • Check API errors: Open the browser developer tools (F12 -> Console tab) to see if API calls are returning error messages.
  • Verify user role: Some features are only visible to certain roles. Check that the user has the appropriate role for the action they're trying to perform.
  • Database consistency: If data seems inconsistent, check the raw data in Prisma Studio (pnpm db:studio) to verify actual database values.
  • Recompute payroll: Many payroll issues can be resolved by recomputing the payroll run. This recalculates all values from scratch, including reversing and re-applying loan payments and adjustments.