How to fix DELETE_FAILED in Salesforce deployments

A record delete is blocked by a lookup relationship, a trigger, or a pending approval, separate from the metadata-level DEPENDENCY_EXISTS.

Surfaces during: runtime DML deletes, in data loads, batch jobs, and Apex tests

What it means

DELETE_FAILED is a data-level error returned when a DML delete operation can't complete, usually because another record still holds a lookup or master-detail reference to it, a trigger vetoed the delete, or the record is locked by a pending approval. It applies to record deletes during data loads and Apex tests, not to deleting metadata components.

Master-detail children are deleted automatically when the parent is deleted, so this error is almost always about a lookup relationship, where Salesforce leaves the choice of cascade-or-block to the field's configuration, or about custom logic explicitly stopping the delete.

Diagnosis

Common causes

Child records still reference the record via lookup

A lookup field on another object points to the record being deleted, and the relationship isn't set to cascade or clear automatically.

A trigger or validation rule blocks the delete

Custom Apex or a validation rule on the object explicitly prevents deletion under certain conditions, such as a status check.

Record is locked by an approval process

The record is mid-approval, which Salesforce won't let you delete out from under.

The fix

Delete or reparent child records first
Remove or update the lookup on dependent records before deleting the parent, or change the field to clear on delete if that's the correct behavior.
Review trigger and validation rule logic
Check for delete-blocking logic in Apex triggers (trigger.isDelete) and validation rules that fire on delete.
Cancel or complete pending approvals
Resolve any in-flight approval process on the record before attempting the delete.

In practice

How Serpent prevents this

Serpent's preflight checks flag records and dependent metadata a task's data changes would affect, so a blocked delete shows up before a release instead of failing mid-deploy. See the Salesforce deployment error library.

No-code CI/CD pipeline builder in Serpent

Prevention

Decide cascade behavior at field design time

Choose "Clear the value of this field" versus "Don't allow deletion" deliberately when creating a lookup, instead of discovering the default the hard way in a bulk delete.

Wrap batch deletes with a dependency pre-check

Query for child records and pending approvals before a bulk delete job runs, and skip or report blocked parents instead of letting the whole batch fail.

Document delete-blocking triggers where they aren't obvious

Comment any trigger that vetoes deletes based on status or business rule, so future data cleanups don't hit the error blind.

Common questions

DELETE_FAILED, answered

Is DELETE_FAILED the same error as DEPENDENCY_EXISTS?

No. DEPENDENCY_EXISTS blocks deleting metadata, like a field or object, because other metadata references it. DELETE_FAILED blocks deleting a data record because other records or automation reference it.

Why does deleting the parent work sometimes but not other times on the same lookup?

The lookup field's delete behavior is per-field, not automatic. If it's set to clear the value on delete, the parent deletes fine; if it's set to restrict deletion, any child reference blocks it.

Does moving the record to the Recycle Bin count as deleted for this check?

Yes, a soft delete to the Recycle Bin still triggers the same dependency and trigger checks as a hard delete; the record isn't gone until the bin is emptied, but the DELETE_FAILED check runs at the soft-delete step.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Start free Book a demo