Common Errors During Worker HDL Load in Oracle Fusion HCM (With Solutions)
Loading worker data using HDL (HCM Data Loader) in Oracle Fusion HCM is powerful—but even small configuration or data issues can cause errors that block the load process.
In this blog, we’ll cover 10 common Worker HDL load errors, explain why they occur, and provide clear, step-by-step solutions to resolve them quickly.
1️⃣ Error: You Must a Primary Value
🔍 Cause
The system requires a primary work term for the worker, but it is missing.
✅ Solution
Add the PrimaryWorkTermsFlag attribute in the WorkTerms metadata and set it to Y.
Tip:
Each worker must have exactly one primary work term.
2️⃣ Error: Person can have only 1 active Primary WorkRelationship
🔍 Cause
The worker already has an active primary work relationship, and a new one is being created.
✅ Solution
Update the termination date of the previously terminated work relationship to ensure only one active primary work relationship exists.
3️⃣ Error: SourceSystemOwner is unknown
🔍 Cause
The SourceSystemOwner value in the HDL file does not match the lookup configuration.
✅ Solution
-
Navigate to Setup & Maintenance
-
Search for Manage Common Lookups
-
Open lookup type
HRC_SOURCE_SYSTEM_OWNER -
Remove FUSION from the custom lookup code
-
Update the same value in the Worker.dat (or relevant HDL file)
-
Zip and reload the file via
My Client Groups → Data Exchange → Import and Load Data -
Refresh and verify successful completion
4️⃣ Error:
JBO-FND:::FND_FLEX_SEG_VAL_NOT_IN_LIST: xxx is not in the list
🔍 Cause
The Site Code linked to the Position is invalid or expired.
✅ Solution
-
Remove the end date for the Site Code
OR -
Extend the end date for the Site Code
After correction, reload the Worker HDL file.
5️⃣ Error: You must enter a valid value for the GradeId field
🔍 Cause
An invalid or missing grade is passed for a position-based assignment.
✅ Solution (Choose one):
-
Provide the correct GradeId or GradeCode
-
Pass
#NULL(withPER_ENFORCE_VALID_GRADE = Y) -
Set
PER_ENFORCE_VALID_GRADE = Nto skip grade validation
📌 After loading, run the ESS job:
Synchronize Person Assignment from Position
This syncs grade, job, and other position attributes.
6️⃣ Error: The values xxxx aren't valid for the attribute LegislationCode
🔍 Cause
The Legal Entity registration setup is incomplete or duplicated.
✅ Solution
-
Go to Setup & Maintenance
-
Navigate to Legal Structures
-
Assign a unique Registration Number
-
Save and reload the Worker HDL file
7️⃣ Error:
METADATA line for the {BO_NAME} business object is invalid
(While loading Person Extra Information)
🔍 Cause
Outdated Worker HDL template or missing EFF attributes.
✅ Solution
-
Refresh the Worker HDL object
-
Download the latest Worker template
-
Update the file with:
-
FLEX attributes
-
Follow Oracle documentation for Extensible Flexfields
-
Zip and reload via Import and Load Data
8️⃣ Error:
You cannot update this record because the SourceSystemId and SourceSystemOwner are invalid
(Assignment Supervisor)
🔍 Cause
Mismatch between source keys and Fusion surrogate keys.
✅ Solution (Best Options):
-
Remove SourceSystemId/Owner and use Fusion surrogate or user keys
-
Ensure parent and child objects use the same key type
-
For integrations:
-
Update mappings using
HRC_INTEGRATION_KEY_MAP -
Load mappings via SourceKeys.dat
-
Reload AssignmentSupervisor data
-
9️⃣ Error:
You must provide only one parent record Worker and it must start on the earliest effective start date
🔍 Cause
Incorrect Worker effective dates or duplicate Worker records.
✅ Solution
-
Ensure StartDate = EffectiveStartDate
-
Match the earliest date from
PER_ALL_PEOPLE_F -
If creating only a new assignment or work relationship:
-
Remove
METADATA Worker -
Remove
MERGE Workerrecords
-
🔟 Error: No Assignment record from 2018-10-27
🔍 Cause
Assignment data is missing from the Worker HDL file for the specified effective date.
✅ Solution
Add the Assignment record in Worker.dat starting from 2018-10-27, then reload the file.
✅ Best Practices for Worker HDL Loads
-
Always use the latest HDL templates
-
Validate effective dates carefully
-
Avoid mixing Fusion surrogate keys and source keys
-
Run required ESS jobs after position-based updates
-
Test loads in DEV or TEST before PROD
🔚 Conclusion
Worker HDL errors in Oracle Fusion HCM are common—but most are caused by data inconsistencies, configuration gaps, or outdated templates. Understanding these errors and applying the correct solution can save hours of troubleshooting and ensure smooth data loads.
💬 Have questions or faced a different error?
Drop them in the comments—I’ll help you troubleshoot.
