Troubleshooting Errors when Submitting to HUD

Learn how to solve common errors encountered when submitting to HUD using HomeKeeper's HUD Connect App

+More

Table of Contents

HUD Connect / General Errors Submission Log Error Messages for Failed Submissions Agency Agency Contact Client HUD 9902 and Group Sessions

This article summarizes common error messages in HUD Connect and outlines current solutions. For help with these or any other errors, contact us at support@myhomekeeper.org.

NOTE: Reporting to HUD is an add-on feature set for HomeKeeper. If your program is interested in using HomeKeeper to report housing counseling to HUD, contact HomeKeeper support for pricing/setup information.

HUD Connect / General Errors

HomeKeeper's HUD Connect Cannot Login

This error will display when HomeKeeper cannot log into HUD HCS with the username and password you have provided. Either follow the hyperlink at the end of the message (Agency Settings username and password) or navigate back to the Agency Settings tab to update your login with the correct information.

Reference: HUD 9902 Reporting Period Schedule (Copied from HUD Exchange Website)

HUD Fiscal Quarter	Period Covered	Due Date
1st Quarter	October 1 – December 31	Due no later than January 31.
2nd Quarter	October 1 – March 31	Due no later than April 30. Include clients reported in the quarter 1 report plus new clients served in quarter 2.
3rd Quarter	October 1 – June 30	Due no later than July 31. Include clients reported in the quarter 2 report plus new clients served in quarter 3.
4th Quarter	October 1 – September 30	Due no later than December 31. Include the complete year of client data plus new clients served in quarter 4.

"Web service callout failed" error when accessing HUD Connect App

When accessing HUD Connect app, receive error Web service callout failed: Unexpected element. References !setAgencyRecordId.

This is because HUD Connect was unable to sign in to the Housing Counseling System (HCS) using your password provided in HUD Agency Setting.

Solution: Obtain the counselor's HCS password (reset the password if needed). Then, navigate to HUD Agency Setting in HUD Connect app. Enter it as the Production Password, and save the HUD Agency Setting with this information. This should resolve the error Web service callout failed.

Note: After updating Production Password, you may need to switch from HUD Connect to the Housing Counseling app, and then back to HUD Connect again.

Read how to update your HCS login information from the HUD Agency Setting in HUD Connect.

CMS password is incorrect for CMS Id

Full-text error typically includes a CMS Id # i.e.: CMS password is incorrect for CMS Id [79]. Please resubmit with valid CMS Id and password

This means the Agency's CMS in HCS has not been properly set to HomeKeeper (so HCS expects the submission to come from a different CMS).
Submit the Agency profile again, and (best practice) the Counselor profile. This should allow submissions from HUD Connect's 9902 tab without error.

Notes from HUD: "Every year on 09/30 the system is set up for the new fiscal year. At that time the most recent version of the agency profile is copied into a new record for the new fiscal year. If the agency already has their CMS set then it will be copied over to the new fiscal year."
This means if an agency starts using HomeKeeper mid-year, they may have to submit Agency first until a new HUD FY begins (after 9/30 of that year).

"Refresh HUD Submission Data" button not refreshing

If you are using Internet Explorer or old version of Safari - HomeKeeper has noticed the button "Refresh HUD Submission Data" may not work reliably in the Internet Explorer browser. Please log in at https://login.salesforce.com/ using another browser (such as Google Chrome).

If you are NOT using Internet Explorer and your Browser is up-to-date - This is likely due to an APEX error that prevented HUD Connect from completing the job. Check your email (or ask your administrator) for an email notification. You can also check these in Setup → Apex Jobs.

If you did not receive a message, or are unable to interpret it, please contact support@myhomekeeper.org.

If you encounter an error not listed here, please contact support@myhomekeeper.org and we will be happy to help.

"IO Exception: Unexpected end of file from server" error when selecting HUD Agency

User attempts to select Agency (from either HUD Agency Profile Submission, or HUD 9902 Submission). Receives error IO Exception: Unexpected end of file from serverError is in expression '{!setAgencyRecordId}' in page hudconnect:agencyprofilelistview: (hudconnect)
An unexpected error has occurred. Your solution provider has been notified. (hudconnect)

HUD Agency Profile Submission references !setAgencyRecordId, whereas HUD 9902 Submission references !yearReferenceOptions.

Solution: HUD Server is down (Pilot Server, possibly also Production). This must be fixed by HUD. Please wait and retry. HomeKeeper can inform our HUD contact. You can access 9902 data using this workaround.

"Web service callout failed" error when selecting HUD Agency

User attempts to select Agency, but receives error such as below (formatting added):

Web service callout failed: Unexpected element. Parser was expecting element 'http://schemas.xmlsoap.org/soap/envelope/:Envelope' but found ':HTML' Error is in expression '{!setAgencyRecordId}' in page hudconnect:agencyprofilelistview: (hudconnect)
Web service callout failed: Unexpected element. Parser was expecting element 'http://schemas.xmlsoap.org/soap/envelope/:Envelope' but found ':HTML'Error is in expression '{!submit}' in component <apex:commandButton> in page hudconnect:counselorprofilesubmission: (hudconnect)
An unexpected error has occurred. Your solution provider has been notified. (hudconnect)
Web service callout failed: Unexpected element. Parser was expecting element 'http://schemas.xmlsoap.org/soap/envelope/:Envelope' but found ':HTML'Error is in expression '{!yearReferenceOptions}' in page hudconnect:clientprofilesubmission: (hudconnect)
An unexpected error has occurred. Your solution provider has been notified. (hudconnect)

Solution #1: Confirm the username(s) are in all capital letters, as these are case sensitive for HUD Connect to login to HCS (but not for HCS login through the HUD website).

Solution #2: Obtain the counselor's HCS password (reset the password if needed). Then, navigate to HUD Agency Setting in HUD Connect app. Enter it as the Production Password, and save the HUD Agency Setting with this information. This should resolve the error Web service callout failed. Read how to update your HCS login information from the HUD Agency Setting in HUD Connect.

Solution #3: Navigate to HUD Agency Setting in HUD Connect app. Update the Production Fiscal Year and save the HUD Agency Setting with this information. This should resolve the error Web service callout failed. Read how to update your HCS login information from the HUD Agency Setting in HUD Connect.

Solution #4: The Agency IDs between Pilot and Production Settings don't match. The query is trying to get the Agency Settings record by HCS Id but only looking at the Pilot Agency HCS ID value instead of also looking at the Production Agency HCS ID.

Copy the value from Production Agency HCS ID to the Pilot Agency HCS ID field. This will enable the query in that page to find the Agency Settings record and proceed.

Alternative Resolution: HUD Server is down. This must be fixed by HUD. Please wait and retry. HomeKeeper can inform HCS contact. You can access 9902 data using this workaround.

"Last Refresh Date" on HUD 9902 Submission tab is stuck in "refreshing"

After clicking "Refresh HUD Submission Data", the HUD Connect submission tab shows a "Last Refresh Date" which should save to the final Date/Time that the process completed.

If the "Last Refresh Date" is updating on the tabs 'HUD Agency Profile Submission' and 'HUD Counselor Profile Submission', but on the 'HUD 9902 Submission' tab it is *stuck* to show the text "refreshing", either there is no applicable Counseling/Ed data to report, or the 9902 cannot be generated yet for the HUD Fiscal Year selected in HUD Agency Setting.

If there are no Counseling/Education records that are applicable to generate a 9902, this could be because:

Report to HUD is not checked on any Counseling/Ed records
Session Start Date for the Counseling/Ed records where Report to HUD is checked does not fall within the applicable HUD Fiscal Year

This can occur when setting up an agency to report using HUD Connect for the first time, after a data migration where Session Start Date was not entered as expected, or before the applicable HUD Fiscal Year has begun. A 9902 cannot be generated if there is no data to inform it due to data entry, or the date starting the HUD Fiscal Year has not yet occurred.

“Submissions for Quarter ... are no longer accepted”

This error appears if 1) you are submitting HUD 9902 data after the quarterly reporting period's due date, or 2) you have not updated your settings since the beginning of the HUD fiscal year.

See how to update the HUD Agency Settings, where the field Production Fiscal Year can be edited.

The old error text read: ERROR: Submissions for Quarter 1 (Ref.Id: 2) of Fiscal Year 2017 (Ref.Id: 23) are no longer accepted.

Clicked “Refresh HUD Submission Data” a second time before the first process has finished

If you click Refresh HUD Submission data a second time before the first process has finished, it will not complete the first process and start again, creating duplicate records and an incomplete list.

Solution: Be patient! You can keep refreshing the browser window by hitting “Refresh Agency List.”

You can also go to Apex Jobs in Setup, to see when the process is finished.

Unable to access HCS outside the United States

HomeKeeper understands that if a user is outside the US, cannot login to HCS. This would lead to an error when submitting with HUD Connect.

RESOLVED in HUD Connect 1.7 "Maximum view state size limit" error message" error after submitting to HUD

This error was resolved by HUD Connect 1.7, which increased the size of a detailed submission. In the event the data is too large, a Submission Log Status of "FAILED - CONTACT SUPPORT" so you know to reach out to HomeKeeper.

After selecting HUD Agency Profile Submission, receive error Maximum view state size limit (135KB) exceeded. Actual view state size for this page was..."

This is a known issue that is encountered when the counseling data is too large to load on the results page. The Salesforce Visualforce page cannot load due to insufficient page memory. (First encountered 10/3/17)
- Client Submission Profile Visualforce page (for HomeKeeper developers): https://na35.salesforce.com/06641000004DM0o)
- Salesforce article discussing view state size limit: https://help.salesforce.com/articleView?id=000002955&type=1

Solution: HUD data has been submitted, although the confirmation page cannot load as expected. Check the HUD Submission Log for DONE status.

HomeKeeper's development team (SOPACT) is working on addressing this issue.

RESOLVED in HUD Connect 1.9 Gray box with browser error on HUD Submission tab

*Corrected in HUD Connect 1.9*

This occurs because the browser or browser settings do not permit the red flashing text/"progress" to display while HUD submission data is refreshing.
No known resolution. User can instead rely on "Refresh Agency List" button, or check Setup>Apex Jobs to confirm the processes related to HUD submission refresh is complete.

HomeKeeper has no plans to replace progress indicator unless we undertake a substantial rebuild of HUD Connect.

Submission Log Error Messages for Failed Submissions

Agency

"Agency_Mailing" Submission Log Error

When making a Submission Type of Agency, this error will include text such as:
ERROR: Attempt to insert an invalid value [null] for Agency_Mailing_State. Please use getReference to obtain acceptable values.

Solution: Update the Agency record to include all Mailing address data, or remove all Mailing address data if N/A. Then, "Refresh HUD Submission Data" with button, and re-submit the Agency from the tab "HUD Agency Profile Submission".

This error appears when some Mailing address fields are populated on the Agency record, but *not* the field Agency Mailing Address State. This could be due to a browser autofilling some fields for a user.

Agency Contact

Client

Errors in Submission Log due to blanks, but 9902 Control Reports show "No HUD Corrections Needed" = Check for customizations to picklist fields

As discussed in HomeKeeper onboarding, and noted in the field Descriptions, certain fields should not be customized to prevent 9902 errors. See a list of these fields below.

Application Household Member - Gender
Counseling/Ed - Activity Type
Counseling/Ed - Attributable HUD Grant
Counseling/Ed - Counseling Type
Counseling/Ed - Discrimination Victim
Counseling/Ed - HUD 9902 Income Level
Counseling/Ed - Purpose of Visit
Counseling/Ed - Session Start Rural Area Status
Counseling/Ed - Status
Group Session - Activity Type
Group Session - Attributable HUD Grant
Group Session - Group Session Type
Service File - Colonias Resident
Service File - Educational Attainment
Service File - Ethnicity
Service File - Farm Worker
Service File - Head of Household Type
Service File - HUD Assistance
Service File - Limited English Proficiency
Service File - Marital Status
Service File - Primary Language Spoken
Service File - Race
Service File - Referred By

Submission Log's Status = STARTED or FAILED for a reason unrelated to submission size

You are attempting to submit under a NOFA that is not funded

This may occur because the agency is not funded for the HUD Activity Type that they have indicated on Counseling/Ed with Report to HUD checked in the reporting period.

HomeKeeper assisted an agency that had complete data, >300 Counseling/Ed records and up-to-date HUD Agency Setting, but their Form 9902 Submission Logs were returning Status of FAILED - CONTACT SUPPORT (Internal link to HK Ticket 3036) Note: When Status = STARTED or FAILED, Apex job did not complete, so there is no XML produced to attached to Submission Log.

Support noticed that at the time of 9902 submission, the Apex Jobs had a failed job for Apex Class Form9902DataWebservice, with the Status Detail:
" First error: ApexPages.addMessage can only be called from a Visualforce page "

Our developer identified this error indicates that a field failed validation while building the XML to send to HUD. As currently built, this error does not specify which field failed validation at the time of submission, but in both cases where this error occurred, the suspected field was the Actitivity Type (where that funding source was not or not yet valid for Agency).

Resolution as of January 2021
Confirm the NOFA options are correct for:

Activity Type picklist on Counseling/Ed and Group Session
Setup>Custom Settings>HomeKeeper Housing Counseling Settings> Acceptable 9902 HUD Activity Type

Confirm the HUD funding sources in HUD's HCS. It appeared that they were not funded for a grant that they had attributed Counseling/Ed (using Activity Type). HomeKeeper changed Counseling/Ed field Activity Type to prior NOFA, and this Submission Log processed as expected (Status = DONE)

HomeKeeper intends to devote further hours into providing more transparency for users in these errors.

HUD 9902 and Group Sessions

"Not funded" referenced in Error in Submission Log

The Submission Log Error field indicates the activity in that submission is not funded. Examples of this error include:

Form 9902 activity [<N>] (Ref.Id: <NN>) not funded for agency ID <NNN> or its parent
agency in FY <NNNN> (Ref.Id: <NNNN>).
Group Session activity [<N>] (Ref.Id: <NN>) not funded for this agency or its parent.
Client activity [<N>] (Ref.Id: <NN>) not funded for agency ID <NNN> or its parent agency in FY <NNNN> (Ref.Id: <NNNNN>).

This means the data submitted contains reporting on an activity type/grant that the agency (or its parent agency) was not awarded funds for the fiscal year being reported on. This could be because of delay or miscommunication in HUD awarding funds. In HomeKeeper, this is tracked using field Activity Type.

Resolution options:

On appropriate Group Sessions or 1-1 Counseling/Eds, update Activity Type to "Non HUD Funded Activity", then refresh and resubmit with HUD Connect.
On appropriate Group Sessions or 1-1 Counseling/Eds, update Activity Type to a valid NOFA option for which the agency is funded (this can be confirmed with agency's HUD contact, or by logging into HCS to view HUD Funding Sources). Then, refresh and resubmit with HUD Connect.

Group Session Counselor Id: ### does not correspond to an actual Counselor Profile.

If you've encountered this error in the Submission Log, you may have added a new counselor since the last time your HUD data was submitted. If your counselor data has changed since the HUD fiscal year started, resend counselor data first (from the tab HUD Counselor Profile Submission). Then, resend Client or 9902 data.

"The content of element 'tns:Group_Session_Attendees' is not complete"

The full error will read: LINE: 1 : cvc-complex-type.2.4.b: The content of element 'tns:Group_Session_Attendees' is not complete. One of '{"http://gov.hud.arm/form_9902_databag_5_0":Group_Session_Attendee}' is expected.

This error indicates that a Group Education Counseling/Education record is missing the field Group Education Attendee Contact (if a System Administrator user deleted this read-only field). Use the Counseling/Education list view "Group Education: All" and click the column "Group Education Attendee Contact" to sort it and look for records that are missing this field.

To fix this, you can:

Edit the Counseling/Education record that's missing this field. Clear out the field Application Household Member, and re-select the person who attended, so the field Group Education Attendee Contact will be filled in.
Log in as a System Administrator user to update this field with the Group Education Attendee Contact.
Confused? Grant login access to HomeKeeper Support, and then email support@myhomekeeper.org with the name of the Counseling/Education records that are missing the Group Ed Attendee Contact, and we will help.

“Content of element 'tns:Attendee' is not complete”

These errors were received when the Client ID was blank. This means a Contact is not selected in the Application Household Member record for an Applicant/Co-Applicant. This could occur if user did not use "Enter Applicants".

ERROR: There was a problem parsing your XML submission. Please review and correct these errors, then resubmit.
LINE: 1 : cvc-complex-type.2.4.b: The content of element 'tns:Client_Profile' is not complete. One of '{"http://gov.hud.arm/client_profile_databag_5_0":Client_ID_Num, "http://gov.hud.arm/client_profile_databag_5_0":Client_SSN1, "http://gov.hud.arm/client_profile_databag_5_0":Client_SSN2, "http://gov.hud.arm/client_profile_databag_5_0":Client_First_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Last_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Middle_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Street_Address_2, "http://gov.hud.arm/client_profile_databag_5_0":Client_New_Street_Address_1, "http://gov.hud.arm/client_profile_databag_5_0":Client_New_Street_Address_2, "http://gov.hud.arm/client_profile_databag_5_0":Client_New_City, "http://gov.hud.arm/client_profile_databag_5_0":Client_New_State, "http://gov.hud.arm/client_profile_databag_5_0":Client_New_Zip, "http://gov.hud.arm/client_profile_databag_5_0":Client_Phone_Num, "http://gov.hud.arm/client_profile_databag_5_0":Client_Mobile_Phone_Num, "http://gov.hud.arm/client_profile_databag_5_0":Client_Fax, "http://gov.hud.arm/client_profile_databag_5_0":Client_Email, "http://gov.hud.arm/client_profile_databag_5_0":Client_Birth_DT, "http://gov.hud.arm/client_profile_databag_5_0":Client_Counsel_End_Session_DateTime, "http://gov.hud.arm/client_profile_databag_5_0":Client_Grant_Amount_Used, "http://gov.hud.arm/client_profile_databag_5_0":Client_HECM_Certificate_Issue_Date, "http://gov.hud.arm/client_profile_databag_5_0":Client_HECM_Certificate_Expiration_Date, "http://gov.hud.arm/client_profile_databag_5_0":Client_HECM_Certificate_ID, "http://gov.hud.arm/client_profile_databag_5_0":Client_Mortgage_Closing_Cost, "http://gov.hud.arm/client_profile_databag_5_0":Client_Mortgage_Interest_Rate, "http://gov.hud.arm/client_profile_databag_5_0":Client_Sales_Contract_Signed, "http://gov.hud.arm/client_profile_databag_5_0":Client_Credit_Score, "http://gov.hud.arm/client_profile_databag_5_0":Client_Credit_Score_Source, "http://gov.hud.arm/client_profile_databag_5_0":Client_Second_Loan_Exists, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Is_Hybrid_ARM, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Is_Option_ARM, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Is_Interest_Only, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Is_FHA_Or_VA_Insured, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Is_Privately_Held, "http://gov.hud.arm/client_profile_databag_5_0":Client_Intake_Loan_Type_Has_Interest_Rate_Reset, "http://gov.hud.arm/client_profile_databag_5_0":Client_Spouse_First_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Spouse_Last_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Spouse_Middle_Name, "http://gov.hud.arm/client_profile_databag_5_0":Client_Spouse_SSN, "http://gov.hud.arm/client_profile_databag_5_0":Client_9902_Reporting_Qtr}' is expected.

This error is saying one of these is required and isn't included. You then have to find the required ones in this list, and then look for missing data in the xml file or in a Client View listview. I can usually spot the required field and zero in on the missing data, but in this case, most of these are not required according to: https://files.hudexchange.info/resources/documents/HCS-ARM-Control-Document.pdf

How I fixed (HomeKeeper Support Forum Ticket 2718): Created a troubleshooting listview for HUD Client views and added Client ID. Noticed that ONE record did not have a client ID. Upon further digging, noticed AHHM was created for the Primary Applicant, but no contact was linked in the Contact lookup.

Totals Not Matching / Not as Expected

9902 totals do not match other totals (Counseling Clients, Group Session Attendees, or Group Sessions)

6.1. Apex Job Failure

HomeKeeper has found this is typically because the Apex Jobs that inform the totals are failing. Contact HomeKeeper for troubleshooting (read on below).

If possible, help HomeKeeper troubleshoot by going to Apex Jobs -> Setup and finding the HUD related Apex Jobs that has an error and Failure noted in the list:

6.2. Totals in Purpose of Visit (or other 9902 sections) are GREATER than the Total Counseling

When section totals do not match, we've found the following errors that are typical when:

1) Session End Dates are entered Manually instead of relying on Log Items,

- Check to make sure Session End Dates are greater than Session Start Dates (this causes issues with how we select records to report)

2) 1-1 Counseling records attached to Group Sessions (instead of Group Education Only)

- 1-1 Counseling should not be used for Group Session registration as the data does not match

3) 1-1 Counseling records converted/cloned to Group Education with Purpose of Visit carried over

- Locate any Group Education Counseling/Education records and identify any that have a Purpose of Visit - Group Education records should not have a Purpose of Visit, they derive that from the Group Session.

error resolution hud submission 9902 report to hud failed troubleshoot