Understanding Error Reports and File Structure

Error reports are generated for each file you submit when the TDP system detects potential data quality issues in your file. These can range from issues with the file layout (which can prevent TDP from being able to fully process your files) to issues related to specific records and/or cases in your file.

This guide provides instruction on how to access, understand, and address issues listed in your error reports. Also Included herein is a brief overview of how data is organized in your files.

Please note: The error reports were designed to help you to correct a wide variety of data issues. Most of the errors that may be listed in these reports are based on the file record layouts and coding instructions, which are publicly available and accessible from the TDP home page. These reports do not capture every possible data quality issue. The OFA TANF data team may still reach out to you via email with additional feedback.

Jump to:

• Download and View Error Reports
• Data File Structure
• Overview of the Error Report
• New Coding Instruction Guidance for States and Territories

Download and View Error Reports

Error reports can be accessed from the Data Files page by navigating to the Submission History tab for a given fiscal year and quarter. Read more about accessing Submission History.

To access error reports for submitted files, select the link in the ‘Error Report’ column to download error feedback associated with the relevant version of the file.

Data File Structure

The files that you submit on a quarterly basis for your TANF or SSP program contain large amounts of data in a specific format that enables TDP to process and provide feedback when uploaded and submitted. Please note that these files are designed for system processing and, as such, are not as human-readable. For example, below is an illustration of a short TANF, Section 1 (Active Case Data) file:

Included below are descriptions of how the data files are classified (or recognized) by the system. These classifications determine the data components to be included in each file and how the components are organized.

Classifications of Data Files

Program Type

Files are first identified by their program type: Tribal TANF, TANF (ACF-199), or Separate State Program Maintenance-of-Effort (ACF-209). Each type of data file has its own unique elements, which are documented in the coding instructions linked below.

• Tribal TANF Coding Instructions
• TANF (ACF-199) and SSP-MOE (ACF-209) Coding Instructions

Sections of Data

TANF and SSP-MOE data covering each fiscal quarter period are reported in up to four sections of data files:

Components of Data

Records

Each data file contains between 3 and 5 different types of records (including the header and trailer).

While header and trailer records are included in every data file, the other record types included in each file vary by section. These record types (described below) are referenced in the error message associated with each data quality issue included in the error report. Please note that T1, T2,...,T7 record types are relevant to TANF and Tribal TANF data files, whereas M1,M2,...,M7 record types refer to the SSP-MOE data files.

Header and Trailer Records

The Header and Trailer refer to special records at the beginning and end of every data file. The Header communicates key information to TDP about the file's classification that helps the system correctly process it, including calendar year and quarter, program type, and section. The Trailer contains information about the number of records (excluding the header and trailer records) in the file.

Examples of Header and Trailer records:

Typically, these records will be generated automatically as part of your current process for exporting data files. Please note: TDP does require that the update indicator, one of the items making up the Header record, be set to a value of "D" (meaning "Delete"). The update indicator is an instruction to the system to delete and replace any existing data in the TDP database for the specified quarter, program type, and section with the data included in the submitted file). Read more about how to submit complete data.

Items

Items (sometimes referred to as "data elements") are the building blocks of every record. Items are references to the coding instructions. For example, Item 11 of Section 1 of the TANF Data Report is "Number of Family Members". Each data quality issue in the error report will, if applicable, include the associated Item Number and Item Name for reference to the coding instructions, which include all acceptable values for each item, their meanings, and guidelines for their use.

Some items have a static list of acceptable values, such as the Item 10 (Newly-Approved Applicant), where the acceptable values are either "1" (Yes, a newly-approved applicant) or "2" (No). Others, like Item 32 (Date of Birth), have a broader range of specific formats for which to report values (e.g. YYYYMMDD).

Overview of the Error Report

TDP's error reports are designed to provide you with key information you may need to quickly identify records that have been flagged for data quality issues. This includes the following:

• Case Number, Year, and Month — which can be used to identify which cases have errors and the reporting period those errors are specific to (if applicable).
• Error Message — which describes the error and how the related items are logically connected.
• Item Number and Item Name — which can be used alongside the error message to cross-reference with the coding instructions.
• Internal Variable Name — a value specific to TDP's database for use in support sessions with the TANF data team.
• Row Number — identifying which row of the submitted file contains the record associated with a given error.

Examples of Common Errors

Below are examples of error messages associated with common issues that may be listed in an error report.

Errors related to header or trailer records:

Header-related errors are often the result of submitting files for a fiscal period that is not consistent with the time period in the header record (e.g. trying to submit 2022 data for a 2024 submission). Other header or trailer errors may be related to how the file was generated (e.g. the file produced is missing a header or trailer record). Some examples of how these types of error may appear in your error report are included below:

Please refer to the Transmission File Header Record definitions to compare your file's header or trailer to the expected layout.

Errors related to record length:

Record length-related errors will be raised if the specified record is not aligned with the record layout requirements. For example, this kind of error may appear as follows in the report:

Please refer to the Transmission File Layout documents to compare your records against their expected layouts.

Errors related to invalid values for a specific item/data element:

Invalid value errors can come up when a specific item/data element has an unexpected value (e.g. a letter or a symbol was reported for the zip code field, such as: "462$1"):

To remedy these type of issues, you can compare the value reported in the file for a given item number to the allowable values in the coding instructions associated to the relevant item number. The coding instructions are linked below:

• Tribal TANF Coding Instructions
• TANF (ACF-199) and SSP-MOE (ACF-209) Coding Instructions

Errors related to inconsistent values for related items/data elements in the same record:

Some errors may require review of the coding instructions for multiple items (and their respective values) to determine the proper correction. In the example below, the error is communicating that the value reported for Item 49 is in a conflict with the value for Item 30 in the same record. This message suggests a problem with either the value of Item 49 or the value of Item 30. Refer to the coding instructions and your own data to determine which value needs to be corrected.

Errors related to inconsistent values across related records:

Errors with inconsistent values across related records may require review of the coding instructions to determine the proper correction. In the example below, the error is communicating that a T1 (family) record was found in the file that did not have a corresponding T2 (adult) or T3 (child) record, which effectively means that person-level records associated with this family are missing from the file.

New Coding Instructions Guidance for States and Territories

Some errors flagged in error reports may be associated with values and/or fields that have been deprecated by the updated coding instructions for states and territories. You can refer to the public guidance for a timeline to correct these.

If you submit files based on the old instructions, this will not negatively impact your submission, work participation rates, or published data. You will, however, begin to see errors in the TDP error reports that reflect the new instructions, but these errors will not impact whether your data is accepted.

Please contact the data team at tanfdata@acf.hhs.gov with any questions.