Skip to main content

Troubleshoot XML Errors in FPS (Full Payment Submission) in UK Payroll

This guide outlines how to troubleshoot common XML errors based on the response received from HMRC.

Updated this week

What's covered in this guide?:

Step-by-Step: Troubleshoot XML Errors in FPS Submissions

When submitting a Full Payment Submission (FPS) to HMRC, errors can occur if the XML structure or data doesn’t meet required standards. HMRC returns a response file containing detailed messages to help pinpoint and fix these issues.

Download the XML Response

To download the XML response:

  1. Go to Payroll > RTI > FPS

  2. Click ‘View Details’ next to the submission showing errors

  3. Click ‘Response XML’ to download the error response file.

1. Identify the Error <Location>

To quickly find the error location in the XML:

  1. Press Cmd + F (Mac) or Ctrl + F (Windows)

  2. Search for <Location> in the XML file

Example:

This means the issue lies in the <TaxCode> element within the <Payment> section of the first employee in the submission (fps:Employee[1]).

Another Example:

This refers to the <AORef> element, which is your HMRC Accounts Office Reference. The Accounts Office Reference you entered doesn't follow HMRC’s required format. It should look something like 123PA00012345 — all uppercase, no spaces or special characters.

You can find and update this in Payroll > Payroll Settings > Company Setup.

2. Identify the Employee in the Request XML

To cross-check this in the original submission, download the Request XML:

To locate the employee referenced in the error:

  1. Download the Request XML file.

  2. Press Cmd + F (Mac) or Ctrl + F (Windows).

  3. Search for <Employee>.

    1. If the <Location> tag in the Response XML error says fps:Employee[1], this means the first <Employee> element in the file is the one related to the error.

      • So if it’s fps:Employee[1], go to the first <Employee> result.

  • If it’s fps:Employee[3], go to the third <Employee> element, and so on:

Important: If the <Location> tag refers to fps:Employee[1], the first <Employee> element you find in the file is the one related to the error.

This allows you to match the XML structure directly to the employee’s record and confirm which data field needs updating.

3. Understand the Error Message in the <Text> Field

In the Response XML file which displays all FPS errors, there will be a <Text> field above each <Location> tag that describes what went wrong:

Common error types:

  • Missing or Empty Value: 

    <Text>Value '' doesn't have the correct format</Text>

    This means the field is empty or not formatted correctly (e.g., missing a tax code).

  • Incorrect Format: 

    <Text>Element 'TaxCode' must only have valid text as its content</Text>

    This indicates the value provided is invalid (e.g., incorrect characters or format).

  • Missing or Empty Value: 

    <Text>Invalid content found at element 'NINO' </Text>

    This means that the National Insurance Number is invalid or has incorrect format.

4. Fix the Error

If the Value Is Missing or Empty:

Ensure that the affected field (like TaxCode) is filled in correctly.

  • Correct: 1257L

  • Incorrect: blank, !!!, null

If no value is required, remove the element or use a default where appropriate.

If the Format Is Incorrect:

Check that the value matches the expected format. Avoid invalid characters, empty spaces, or incorrect codes.

5. Validate and Resubmit the XML

After correcting the error:

  1. Review the XML structure to ensure all errors have been addressed.

  2. Re-submit the corrected FPS file to HMRC via the + Submit New FPS Request button in Payroll > RTI > FPS.

Need Help?

If you need assistance troubleshooting XML errors in FPS:

UK Payroll Forms (P32, P45, P60)

Did this answer your question?