The statutory-output screen blocks generation when the selected template, schema, payroll run, organisation/employee readiness, or the pack captured by that run cannot produce a current validated file.

What this means

In Documents > Statutory Filings, the “Official template catalogue” shows a Validation state, Generated status, Submission status, and row actions. “Readiness” can be “Blocked”; a validation preview can have blocking issues; or “Generate” can remain disabled because the backend says the preview cannot generate.

Common causes

  • The run’s captured pack is unavailable or unsupported, or no output catalogue is loaded. The current workspace default selects packs for new preparations; it does not replace an existing run’s captured pack.
  • The output is payroll-run scoped but no current payroll run is selected.
  • Organisation or employee statutory readiness has blocking issues.
  • The installed template schema is invalid or its hash no longer matches the descriptor.
  • The validation preview is missing, stale, has zero eligible rows, skipped employees, or blocking issues.
  • A required employee field, statutory identifier, transaction/reporting bucket, period, currency, or pack-defined output fact is missing.
  • A previous output is Failed or Superseded and needs a fresh validation before regeneration.

How to fix it

  1. In Documents > Statutory Filings, select “Refresh” and confirm the template count and active run context.
  2. Read the “Readiness and evidence” card. Follow “Open organisation profile”, “Open employee readiness”, or “Open proof bundles” when the visible blocker points there.
  3. Confirm the pack identity and output coverage attached to the selected payroll run. For new payroll work, open Statutory Packs and review the workspace default for the statutory date; a pack installed for review is not that default. If a required release is missing or an update is unavailable, use App update or statutory pack update unavailable.
  4. Select “Validate” for the affected row or “Validate all”. In the evidence dialog, inspect “Status”, “Eligible rows”, “Skipped employees”, “Issues”, schema validation, and each issue’s employee, field, column, and message.
  5. Use the issue’s “Open” action to repair the employee or organisation record. Return to the output and validate again; a previous preview is not current after the source data or pack changes.
  6. When the preview can generate and schema validation is valid, select “Generate” or “Regenerate”. Then use “Download latest” and inspect generated history, hashes, and submission status.

What to check before continuing

The row should show a current successful validation, no blocking issues, an enabled generation action, and a Generated file after generation. For ZIMRA earnings outputs, inspect the bucket coverage panel and confirm no required bucket is blocked. Preserve the output ID, validation run ID, file hash, template hash, and statutory pack hash.

Important submission boundary

The screen includes a disabled “Submit to authority” action. “Simulate submission” and a displayed “Accepted” or “Submitted” status are local evidence/status operations; they do not prove that the authority received a filing. Download the generated file and submit it through the applicable official channel, retaining the official receipt.

How to prevent it

Keep workspace defaults current for new payroll preparations and maintain employee/organisation statutory data for each run. Validate after material payroll changes, review schema/template and hash evidence before sharing a file, and use the generated output linked to the correct payroll run.

Still stuck

Record the output ID, organisation, payroll run/period, pack version, validation status, issue code/message, and schema/hash details. Do not edit a generated file to bypass validation or claim submission from a blocked/simulated state. Share selected evidence through support.

Related guideReview payrollRelated guidePayroll preparation checklistRelated guideApp update or statutory pack update unavailableRelated guideSupport cannot see my payroll data