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

What a bounce looks like

DIR's current Upload eCPR guide shows two things you may see after an upload.

Which DIR documents are current

Three DIR files define the format. As of October 16, 2026:

• Guidelines: Version 2.0, March 2026. It is the version on DIR's Public Works Support Center, and the one the Upload eCPR guide links to (eCPR XML Guidelines).
• Schema: version 1.3. DIR's certified payroll reporting page names it V1.3, as does the schema's own header comment. The page does not link the file, but it is served at the address in its namespace.
• Sample file. CPRSample.xml, linked from the same page.

One trap: that page still links an older guideline whose cover reads January 2016, Version 1.10 (eCPR XML Guidelines, 2016). Where it differs from Version 2.0, this page follows Version 2.0:

The rules in the published schema and guideline

Each rule names its source: the schema, or the Version 2.0 guideline (2.0). A validator enforces schema rules. Rules found only in 2.0 you have to check yourself. DIR does not publish a list of what the portal itself rejects, so a file can pass every rule here and still fail on the portal.

1. Employee name id (2.0 step 8, schema note). Each employee's name element carries an id attribute: social security number, two colons, then the worker's name. Step 8 of Version 2.0 says the name must be all upper case (eCPR XML Guidelines, Version 2.0). The older January 2016 Version 1.10 guide already says the same in step 11 (eCPR XML Guidelines, 2016), so Version 2.0 did not add the rule. The schema's note on the name element states it too: NAME is the name of the worker in uppercase, with the example id="123456789::JOHN SMITH" for worker John Smith (CPR XML schema). That example is first name then last name. The example in DIR's Upload eCPR guide, a screenshot of a sample file, shows id="617742834::WADE DWyANE" with the element text WADE, DWyANE, which reads last name then first name. DIR does not say which order the portal expects. The SSN in the id must match the ssn element. The schema types the id as plain text, so a validator will not flag lower case, a wrong SSN, or any other wrong id. One payroll vendor reported in April 2025 that the way employee names are presented in the XML file needed a software change after DIR's new site launched (vendor note). The note does not say what the change was.
2. Social security number (schema). Exactly nine digits, no dashes, per the ssn element. The eCPR carries the full number, unlike the federal WH-347, whose instructions call for only the last four digits of the worker's SSN, or another worker-specific identifying number, and say the full SSN must not be included (WH-347 instructions).
3. Withholding exemptions (schema). One or two digits. Not blank, not a decimal.
4. Dates (schema, 2.0 step 6). Written yyyy-mm-dd, everywhere: the week ending date and every day worked. A date written 02/01/2015 fails validation against the published schema.
5. Days (schema, 2.0 step 9). Exactly seven day elements per employee, in the week that ends on the week ending date. The schema rejects six or eight, so enter zero hours for a day not worked rather than leaving it out. The schema types the day id as an optional whole number and does not check its value, so a validator will not flag wrong day numbering. Version 2.0 says day ids begin at 1 and run for each day included in the payroll, with the same number of days for every employee. Number the seven days 1 through 7 yourself, which satisfies both. Each day's hours must be under 100, with at most two decimal places. The schema checks only that each date is a valid date, so confirm they fall inside the week yourself. DIR's own sample does not: its week ends 2015-02-01 but its days run 2015-12-01 to 2015-12-07, so do not copy dates from it.
6. Project block (2.0 step 3, schema). Project ID is the only field Version 2.0 calls mandatory, and it must match the project you are submitting for (eCPR XML Guidelines, Version 2.0). The schema wants digits only in projectID, 1 to 18 of them. It also still requires a contract agency of at least one character and an empty contractAgencyID element, so fill in the first and leave the second empty. The table below has every element.
7. Payroll number and amendment number (2.0 step 5, schema). Leave them empty. Version 2.0 says the eCPR system assigns both, and the schema fixes both to empty, so a value fails validation against the published schema.
8. Statement of non performance (2.0 step 11, schema). If the week is a no work week, the flag is true and there are no employee records. Keep the employees element, empty.
9. Deductions, contributions, and payments (schema, 2.0 step 12). The schema groups fourteen categories under one block: federal tax, FICA, state tax, SDI, vacation and holiday, health and welfare, pension, training, fund administration, dues, travel and subsistence, savings, other, and a total. Each is a plain decimal amount, and the schema's note says to check with accounting on what belongs in each. Version 2.0 adds a rule on units: fringe benefits, with pension as its example, take hourly amounts, and deductions take the lump sum for the pay period, as in $121.22 for FICA. It does not say which of the fourteen count as fringe benefits beyond that example.
10. Notes (schema, 2.0 step 10). Up to 256 characters. The element must be present, but 2.0 says it is not mandatory and can be left blank.
11. License type and registration (schema). The license type is CSLB, PL, or OTHER, in capitals; for OTHER, put the license type and number in the license number element. The public works registration number is ten digits or a literal NA. Labor Code 1725.5 requires registration to work on a public works contract, with exceptions in subdivision (f) (registration explained).
12. Lengths and codes (schema). Contractor name and contract agency, 1 to 56 characters. Street 1 to 40, city 1 to 25, state two capital letters, ZIP five digits. FEIN nine digits, no dash. Insurance number 1 to 40 characters, NA if you are not required to hold workers' compensation. Check number 1 to 20 characters: CASH for cash, or the transaction number for direct deposit. No more than 500 employees in one file.
13. Amendments are new records. DIR's current FAQ says you cannot change or delete a submitted record, but you can correct an error by submitting a new record for the same pay period. The new or amended record for an employee takes precedence over the original, and the original stays on file, visible along with all its amendments (DIR Public Works FAQ). If you are correcting only some workers, the FAQ says you do not need to resubmit the workers whose information was entered correctly. The upload form asks whether the XML is an amendment to a previous payroll. DIR's FAQ does not publish a list of fields the new record must match to the original.
14. File name (2.0 section 5). The file must end with the extension xml, for example testpayroll123.xml. The last four of the FEIN, project ID, and week ending date pattern is from Version 1.10 and is not in the current guideline.
15. Declaration and namespace (sample, schema). DIR's sample XML file opens with an XML declaration naming UTF-8 and declares the DIR namespace as xmlns:CPR on the root eCPR element. The schema puts every element in that namespace, so a file with no namespace or a different one fails validation against the published schema.
16. Numbers that should reconcile (schema notes). Two relationships are worth checking, and the CPR XML schema documents only part of the second. First, the schema's note says the total hours fields are the week's straight time, overtime, and doubletime hours added up from the daily elements, so each total should equal the sum of its daily hours. Second, gross amount earned has two figures: thisProject for work on this project, and allWork for all of the worker's work that week, including other projects. The schema's example is $960 for this project and $1200 for all work, and its note says the two amounts should be equal when the worker has only this project. The schema does not say what to expect when they differ. Our own reading is that gross for this project should not exceed gross for all work, because all work includes this project. The schema types each of these fields as a bounded decimal and does not compare any of them with another, so a validator will not flag a mismatch. Check both yourself before you sign. The schema documents no calculation for the deductions total or net wages, so this page gives no rule for them.
17. Element order and empty elements (schema). 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. Dropping the empty contractAgencyID or notes element, or swapping two deduction elements, fails validation against the published schema.

The project block, field by field

The project block is a fixed sequence named CPR:projectInfo. Every element below must appear, in order, even when empty, per the CPR XML schema and DIR's sample file.

Version 2.0 says to provide any project details that are available, but the schema fixes awardingBody, contractAgencyID, projectName, and the six projectLocation fields to empty, and a validator rejects a value in any of them. Follow the sample and leave them empty. Version 2.0's screenshot of this block also omits contractAgencyID, while the schema and the sample include it, so keep it.

What to do when it bounces

1. Read the System message, if there is one. If it says the form does not match the XML data, compare the contractor and DIR Project ID on the form with the contractor information and projectID in the file.
2. Open Version 2.0 and the sample file and compare your file's structure to the sample, element by element, in order.
3. Validate against the published schema in an XML editor. Version 2.0 recommends Notepad++ or XML Notepad for validating XML files against a schema file. Then check by hand what the schema cannot: the name id, the day numbering, the dates inside the week, the hour totals, and the gross amounts.
4. Check the usual suspects first: the form match, the name id, the SSN format, the dates, the day numbering, and any populated payroll or amendment number.
5. If it still fails, wait a few minutes in case it is still processing, then click refresh in your browser, as the Upload eCPR guide says. If the problem persists, email publicworks@dir.ca.gov with the exact error text. DIR's Public Works Contacts page lists that address for questions about the electronic certified payroll reporting system. Keep the email and the confirmation with your records.

When it is the state's system, not your file

Not every bounce is a bad file. A portal that will not load or times out can point at the state's system, not your XML. The Upload eCPR guide says processing takes several minutes, so give it time and click refresh in your browser. If the problem persists, email publicworks@dir.ca.gov, the address DIR's Public Works Contacts page lists for questions about the electronic certified payroll reporting system.

DIR has acknowledged in writing that contractors have had trouble getting its eCPR system to accept payroll data. A notice on its public works notices page, dated December 2015, says DIR has "heard about" contractors having difficulty submitting complete or accurate eCPRs because of problems with the form or in getting the DIR system to accept data from their own payroll software. The notice is addressed to awarding bodies and prime contractors who may be withholding progress payments. It says DIR does not want contractors penalized for that difficulty, and it asks them not to rely only on what the eCPR database shows. It does not mention the Labor Commissioner's late filing penalty, and it is not a notice about a current outage. That penalty is in Labor Code 1771.4(a)(3)(B) and (C): $100 a day up to $5,000 per project, not levied until the records are 14 days late. Subdivision (d) of that section applies the penalty to public work on or after January 1, 2016, so the December 2015 notice came before it applied. Treat the notice as a reason to document a real outage: screenshot the error and keep your email to DIR as the record.

How we prepare the file

WellStanding prepares the WH-347 and the eCPR from the payroll export you already run, and a person reviews every filing. Before anything is written, our engine checks the eCPR XML against our own copy of the state file format. That copy is our own reconstruction, not DIR's file, so we do not claim it matches DIR's validation. You review the finished filing and sign the certification in one step, and nothing is filed until you have signed. The certification is always yours; we never sign for you. The declaration under penalty of perjury belongs to the contractor under Labor Code 1776(a) and 8 CCR 16401. We cannot control what DIR's portal does with a file, and as the sections above show, a bounce can come from the form match or from the state's system, not only from the file. For the full workflow around that signature step, see how to submit certified payroll to DIR.

Questions