How to fix FIELD_FILTER_VALIDATION_EXCEPTION in Salesforce deployments

A lookup field value doesn't satisfy the lookup filter configured on that field.

Surfaces during: runtime DML, wherever a lookup value is set, including Apex tests

What it means

FIELD_FILTER_VALIDATION_EXCEPTION means a lookup or master-detail relationship is being set to a value that fails the lookup filter defined on that field. Lookup filters restrict which records can be selected based on criteria like status or record type, and Salesforce enforces them on every save, not just through the UI.

Unlike a validation rule, a lookup filter is configured on the field itself in Setup rather than written as a formula, so it's easy to forget it exists until seed data or a migration script sets a value the filter was designed to reject.

Diagnosis

Common causes

Migrated data links to a record that fails the filter

A migration script sets a lookup to a record whose status or type doesn't meet the destination org's current filter criteria.

A lookup filter was tightened after the seed data was written

The filter's criteria changed in a later release, and existing test or seed scripts weren't updated to match.

Test setup references a record that's since been excluded

Data setup for an Apex test links to a record in a status a lookup filter now excludes, breaking the test on deploy.

The fix

Update migration or seed data to meet current filter criteria
Point the lookup at a record that satisfies the destination org's active lookup filter.
Review the lookup filter when deploying data that needs an exception
Temporarily relax the filter if a specific bulk load genuinely needs to bypass it, then restore it afterward.
Audit lookup filters after object model changes
Whenever a filter's criteria changes, check existing automation and test data for references that would now fail it.

In practice

How Serpent prevents this

Serpent validates deployments against the target org's current metadata before promoting a task, so a lookup filter tightened in a later release surfaces during CI rather than during a production data load. See the Salesforce deployment error library.

Metadata and data in one deployment flow in Serpent

Prevention

Document every lookup filter's criteria alongside the field

Keep a short note on the field's description or in schema docs describing what the filter restricts, so future migrations know the constraint exists.

Treat lookup filter changes as breaking changes to review

Flag any deployment that tightens a lookup filter's criteria for a check against existing automation and test data before it merges.

Keep test setup records aligned with current filter criteria

Re-review Apex test data factories whenever a lookup filter on an object they touch changes, not just when the test itself changes.

Common questions

FIELD_FILTER_VALIDATION_EXCEPTION, answered

Does a lookup filter block API inserts the same way it blocks the UI?

Yes. Lookup filters are enforced on every save regardless of whether the record came from the UI, the API, or a data load.

Is a lookup filter the same thing as a validation rule?

No. A lookup filter is configured directly on the lookup field in Setup and restricts which records can be selected; a validation rule is a separate formula-based check that can reference any field on the record.

Can a lookup filter be optional rather than required?

Yes. Salesforce supports both required filters, which always block non-matching records, and optional filters, which only warn the user in the UI but don't block API or Apex inserts.

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

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

Start free Book a demo