Validation keeps blocking even though the document is uploaded
A staff user (or the client) has uploaded a document, but the cycle still shows a blocking missing document issue. The file is clearly there in the cycle's Files panel — yet validation refuses to accept it. This is almost always one of five things; work them top to bottom.
1. The document type is wrong
The document was uploaded but classified as a different type than the rule asks for. The rule wants passport-photo and the file came in as passport-bio-page. Validation matches on document type (the classification), not just the presence of some file on the line.
Check: open the cycle's Files tab and find the file the client uploaded. Each file shows a Type chip — that's the type the platform inferred (or the client picked) at upload time. Compare it to the type the rule expects, which is shown on the cycle's Issues tab in the issue's detail ("Missing: NRIC front page for joiner Tan Wei Ling").
Fix:
- If the file is correct but the type chip is wrong, edit the file's type from the Files panel — the validation re-runs automatically and clears the issue.
- If the file is genuinely the wrong document (passport bio page instead of NRIC front page), ask the client for the right one via Request info from client.
2. The document is on the wrong change line
The document is uploaded but attached to a different change-line than the rule expects. A joiner-doc rule for Tan Wei Ling won't be satisfied by a passport file attached to the leaver line for Lim Eng Heng, even on the same cycle.
Check: open the file in the Files tab and look at the Linked to field — it shows which submission item (joiner / leaver / change) the file is associated with. The validation issue's detail tells you which item it's looking for the document on.
Fix: re-link the file to the right item. If your role doesn't allow re-linking, delete the file and ask the client to re-upload it on the correct line. The cleaner path is usually to send a Request info from client ask explicitly naming the change-line.
3. The document rule changed mid-cycle
The validation rule the cycle is checking against is the one configured at cycle initiation. If a Payroll Lead updated the document rules after the cycle started, the cycle keeps using the old rule set — the change doesn't apply retroactively.
Check: open the client → Document rules tab. Note the Updated at timestamp on the rule the issue references. Compare it to the cycle's Created at timestamp on the cycle page.
Fix:
- If the updated rule is now correct and the original rule was wrong, the cleanest fix is to override the issue once —
PAYROLL_LEADonly — and let the cycle proceed. See Override an issue. - For future cycles, the new rule applies automatically — no further action needed.
- If you genuinely want this cycle to re-validate against the new rules, that's a re-initiation, not an in-cycle change. Talk to your Payroll Lead before going down that path; it discards the existing submission state.
See Configure document rules per change type for how the rule set is structured.
4. Validation hasn't been re-run since the upload
The file landed but validation is still showing the pre-upload result. The platform re-validates automatically after most file events, but on rare occasions — particularly when a file is moved or its type is edited rather than newly uploaded — the validation cache lags.
Check: open the cycle's Issues tab. Look at the Last evaluated at timestamp at the top of the panel. If it's older than the file's upload timestamp, validation hasn't picked up the new file yet.
Fix: click Re-run validation on the Issues tab. Wait a few seconds and the issue should clear. If it doesn't, move to cause #1 (the type or link is wrong).
5. The rule is firing correctly, you just need to override it
Sometimes the document genuinely isn't going to come — the client has supplied an alternative (a verbal confirmation, a scan that doesn't match the platform's inferred type but is correct content). Validation will keep flagging until either the matching document arrives or the issue is overridden.
Check: you've ruled out causes 1–4 and the platform is correctly identifying that the expected document is genuinely missing.
Fix: override the issue with a written reason. Only a PAYROLL_LEAD can do this — see Override an issue. The override is permanent on the cycle and recorded on the audit log; use it sparingly and document the rationale.
Still not finding it?
If all five check out and validation is still blocking, the rule itself may be misconfigured for the client (e.g. asking for a document type that doesn't exist in your platform's catalogue). Open the client → Document rules and look for any rule with a malformed required-types list.
For tweaking the rule itself rather than working around it on this cycle, see Configure document rules per change type. The full list of validation rules and what each one checks lives in the Validation rules reference.