---
title: "Troubleshooting, FAQ & Glossary"
space: "Industrial Relations Documentation"
url: "http://buff0k.co.za/ir-docs/sa-guide/troubleshooting-faq"
updated: "2026-11-01"
---

## Troubleshooting

**Workspaces, fields or print formats are missing.**
Preserve the migration output and inspect Error Log/app versions. Reproduce and fix on a restored staging site; then back up and run the controlled migration/build/cache-clear workflow. Do not repeatedly migrate production as a diagnostic shortcut.

**"No South African statutory rate pack is configured for ..."**
The payroll engine has no rate pack covering that date. Add the rate pack for that tax year and migrate — see [Annual Statutory Update](/ir-docs/sa-guide/annual-statutory-update). For back-dated runs, confirm a prior-year pack exists.

**SA Payroll workspace / payroll DocTypes are missing.**
ir requires HRMS (Frappe HR) — installing ir installs HRMS automatically. If payroll features are still missing, confirm HRMS actually installed correctly (`bench --site <site> list-apps`) and re-run `bench --site <site> migrate`.

**PAYE looks wrong (too high / too low / zero).**
Check payroll/slip dates, Payroll Period, Income Tax Slab, rate-pack coverage, rebates/medical benefit record, Salary Component classifications, prior slips/additional salaries and employee age/status. Reprocess only after identifying the mismatch.

**UIF is not capped / employer and employee differ.**
Check the UIF components' *UIF Applicable* flags and that the statutory components are mapped in Payroll Settings. UIF employee and employer should both be 1% of the same capped base.

**ETI is zero for an apparently eligible employee.**
Check age (18–29 from ID number), valid SA ID, months employed (≤24), remuneration below the ETI ceiling, *Hours per Month* set, and that *Disable ETI Calculation* is off in Payroll Settings.

**VAT201 has many "needs review" rows.**
Source items/templates are not classified. Set the item VAT category and use the correct tax template on the source documents, then re-fetch.

**EMP501 will not submit.**
A readiness check failed (missing month of EMP201, unlinked IRP5, missing employer reference, missing directive number). Read the specific message and fix the underlying record.

**Can't delete a posted invoice.**
This is intentional — ir protects the SARS audit trail. Cancel and amend instead.

## FAQ

**Do I need HRMS?** Yes — ir requires HRMS for every installation; there is no payroll-optional mode.

**Does the app file to SARS electronically?** No. It produces internal working papers and audit trails. It does not create the SARS BRS payroll-import/encrypted reconciliation formats; generic CSV/PDF exports must not be uploaded as SARS files.

**Where do the rates live?** In date-effective JSON rate packs (`statutory_rates_<YYYY>.json`), surfaced as Income Tax Slab, Tax Rebates, ETI Slab and Travel Allowance Rate records.

**Where is this guide maintained?** In the Industrial Relations Documentation wiki (`/ir-docs`), under *SA Practitioner Guide* and *SA End-User Guide*.

## Glossary

| Term | Meaning |
|---|---|
| **PAYE** | Pay-As-You-Earn — employees' tax withheld monthly. |
| **UIF** | Unemployment Insurance Fund — 1% employee + 1% employer, capped. |
| **SDL** | Skills Development Levy — 1% employer levy. |
| **ETI** | Employment Tax Incentive — employer incentive reducing PAYE payable for qualifying young/low earners. |
| **COIDA / OID** | Compensation for Occupational Injuries and Diseases Act / Occupational Injury or Disease. |
| **EMP201** | Monthly employer declaration of PAYE/UIF/SDL/ETI. |
| **EMP501** | Annual/interim employer reconciliation. |
| **IRP5 / IT3(a)** | Employee annual tax certificate (IT3(a) where no tax was deducted). |
| **VAT201** | Periodic VAT return. |
| **SETA** | Sector Education and Training Authority. |
| **WSP / ATR** | Workplace Skills Plan / Annual Training Report. |
| **EEA2 / EEA4** | Employment Equity report forms. |
| **SARS** | South African Revenue Service. |
| **CIPC** | Companies and Intellectual Property Commission. |
| **BCEA** | Basic Conditions of Employment Act. |

## You're done

That completes the SA Practitioner Guide. Start at [Overview & Architecture](/ir-docs/sa-guide/overview) if you need to orient a colleague.
