When deploying a CustomField, Salesforce may fail validation with a message like:
There is already a Child Relationship named
[RelationshipName]on[ObjectName].
This error indicates that Salesforce found an existing relationship with the same name, preventing you from creating a new one.
What causes this error?
This error typically occurs when a custom object or field has been deleted but not permanently erased from Salesforce.
When you delete a custom object or lookup/master-detail field in Salesforce, it isn't fully removed immediately. Instead, it enters a "soft delete" state and remains in the Deleted Objects (or Deleted Fields) area for 15 days. During this period, any child relationships associated with that object or field still exist in Salesforce's metadata.
Common scenarios that trigger this error:
Manual deletion: Someone deleted a custom object or field through the Salesforce UI, but it hasn't been permanently removed yet.
Rollback after deployment: You deployed a change that created a lookup or master-detail field, then rolled it back. When you try to deploy the same change again, the original relationship still exists in the deleted objects/fields.
How to identify the issue
The error message itself tells you:
The relationship name that already exists (the
[RelationshipName]part)The object where the conflict occurs (the
[ObjectName]part)
For example:
There is already a Child Relationship named Broker_Proposals on Opportunity.
This means a relationship called "Broker_Proposals" already exists on the Opportunity object, likely from a soft-deleted custom object or field.
How to fix it
To resolve this error, you need to permanently delete (erase) the soft-deleted object or field from Salesforce. This can only be done in Salesforce Classic.
Step 1 - Switch to Salesforce Classic
If you're in Lightning Experience, click your profile icon and select Switch to Salesforce Classic.
Step 2 - Navigate to Deleted Objects or Deleted Fields
For deleted objects:
Go to Setup
In the left sidebar, expand Build > Create
Click Objects
Look for the Deleted Objects link at the bottom of the page
For deleted fields:
Go to Setup
Navigate to the specific object that contains the deleted field
Scroll to Custom Fields & Relationships
Look for the Deleted Fields link
Step 3 - Permanently delete (erase) the object or field
Click Deleted Objects or Deleted Fields
Find the object or field that contains the conflicting relationship
Click Erase to permanently delete it
Once the object or field is permanently erased, the child relationship will be removed, and your deployment should succeed.
Alternative: Wait for automatic erasure
If you're unable to access Salesforce Classic or don't have permission to erase deleted objects, you can wait for Salesforce to automatically purge the deleted object or field. This happens 15 days after deletion.
Useful resources
Disclaimer: These errors are returned by Salesforce directly, rather than Gearset. Even so, we offer guidance based on our combined experience with the Metadata API. Where possible, we try to help guide you to fix or avoid this error. In the case that this isn't possible, we may need to direct you to Salesforce support for further clarification.