DIR eCPR XML upload errors: why uploads bounce and how to fix them

The state's schema is strict in ways the portal does not always explain. Here are the rules it enforces, the mistakes that trip each one, and what to do when the upload validates and then nothing appears.

What a bounce looks like

Two things happen to bad XML. Sometimes the portal names a pattern it could not validate. More often the file appears to upload and then the form stays blank. DIR's own FAQ describes exactly that case, an upload the site accepts that shows nothing when you click to load it, and gives the diagnosis in one line: there is most likely an error in your code, review the submission, resend the corrected file, and if the problem persists email the eCPR inbox at publicworks@dir.ca.gov (DIR eCPR FAQ, problems uploading).

Where the rules live

DIR publishes three things on its certified payroll reporting page: the CPR XML schema (version 1.3), the CPR XML guidelines, and a sample XML file. The guidelines were refreshed in 2026 and the schema was carried forward unchanged through the 2024 portal modernization. Every rule below comes from those documents or from live validation behavior against them.

The rules that bounce uploads

Employee name id format. Each employee record carries an id of the form social security number, two colons, then the name in upper case, last name first. Name formatting is the one thing payroll vendors reported breaking after the portal relaunch (one vendor's transition note).
Social security number or ITIN. Exactly nine digits, no dashes. The eCPR carries the full number, unlike the federal WH-347, which shows only the last four.
Withholding exemptions. One or two digits. Not blank, not a decimal. A live server error names the pattern when this is wrong.
Dates. Four digit year, two digit month, two digit day, everywhere: the week ending date and every day worked.
Days. Numbered from 1, at most seven, each date unique and inside the seven day window that ends on the week ending date.
Project block. Only the DIR project ID is mandatory. The entity you contracted with goes in the contract agency field. The other project fields are present in the sample but empty.
Payroll number and amendment number. Leave them empty. DIR assigns both.
Statement of non performance. If the week is a no work week, the flag is true and there are no employee records at all.
Fringes and deductions use different units. Health and welfare, pension, vacation and holiday, and training are hourly contribution amounts. Federal tax, FICA, state tax, SDI, fund administration, dues, savings, and other are period totals. Travel and subsistence is a payment. The deductions total is the sum of the deductions only, not the fringes.
Notes. Short, and no line breaks. A carriage return in the notes field breaks the record.
License type and registration. The license type comes from the allowed set. The public works registration number is required; the only alternative is a literal NA, which is a bigger problem than a bounced file (registration explained).
Contractor name length. One to fifty six characters.
Amendments must match the original. To replace a submitted payroll rather than create a new one, the contractor SSN or FEIN, the DIR project ID, the contract with name, the week ending date, the craft, and the base hourly rate must match the original exactly. Otherwise DIR treats it as a new payroll.
File name. The last four of the FEIN, the project ID, and the week ending date, separated by underscores, ending in .xml.
Declaration and namespace. A UTF-8 XML declaration at the top and the DIR namespace declared on the root element.
Arithmetic. Daily hours sum to the totals. Gross for this project cannot exceed gross for all work. Net wages fall between zero and gross for all work. The deductions total equals the sum of the deductions.
Element order and empty elements. The schema is a sequence, so elements must appear in the documented order, and placeholder elements that carry no value must still be present, empty.

What to do when it bounces

Open the guidelines and the sample file from the DIR page above and compare your file's structure to the sample, element by element, in order.
Validate locally against the published schema before you upload again. A file that fails the schema on your machine will never load in the portal.
Check the five usual suspects first: the name id, the SSN format, the dates, the day numbering, and any populated payroll or amendment number.
If it validates locally and still fails, resend and email publicworks@dir.ca.gov with the exact error text, as the FAQ directs. Keep the email and the confirmation with your records.

The upload that never bounces

Our engine builds the eCPR from your payroll export and checks it against the published schema and the arithmetic identities before anything is written. A person then reviews the file against the project and the wage determination. You do the two minute review and sign, because the declaration under penalty of perjury is yours (Labor Code 1776). No XML on your desk, ever.

Questions

Does the portal tell me what is wrong?

Sometimes it names a pattern it could not validate, for example on the withholding exemptions field. Often the upload appears to succeed and the form simply stays empty. DIR's FAQ treats that as a code error to fix and resend, and points persistent cases to publicworks@dir.ca.gov.

Can I fix a payroll after it is submitted?

Yes. DIR's FAQ says a submitted payroll cannot be deleted; to correct one you resubmit an eCPR for that workweek and the amended eCPR replaces the original. For a week that had no work, a Statement of Non-Performance for that week ending date amends the earlier submission. The amended file has to match the original on the contractor identifier, project ID, contract with name, week ending date, craft, and base rate, or DIR treats it as a new payroll. Company details entered wrong, such as the address, are changed by emailing publicworks@dir.ca.gov with your FEIN.

Is the manual iForm safer than XML?

It is the same data validated the same way. The iForm means typing every worker every week; XML means producing a file that follows the rules above. Both end in the same review and sign step.