How to fix FIELD_INTEGRITY_EXCEPTION in Salesforce deployments

A value being saved does not match what the field expects, most often a picklist value that does not exist in the target org.

Surfaces during: runtime DML, most often Apex test execution or a data load

What it means

FIELD_INTEGRITY_EXCEPTION means a value failed the platform's own integrity check for a field, commonly a picklist value that is not defined in the target org, or a value that violates a restricted picklist or a type constraint. Picklist values are org-specific metadata, so they have to be deployed and kept in sync just like any other component.

The Metadata API deploys standard-object picklist value changes as part of the object's metadata, so a mismatch here almost always traces back to a picklist value edit that reached one org's Setup but never made it into version control or a matching deployment.

Diagnosis

Common causes

Picklist value missing in the target org

An Apex test or record uses a picklist value that was added in the source org but never deployed to the target org's value set.

Restricted picklist rejects the value

The field is set to a restricted picklist, and the value being saved is not in the org's approved list.

Field type mismatch after a schema change

A field's type changed, for example text to number, and old test data or formulas still assume the previous type.

The fix

Deploy the picklist values first

Include the global value set or field-level picklist value change in the same deployment as anything that uses it.

<valueSet>
  <valueSetDefinition>
    <sorted>false</sorted>
    <value><fullName>Renewal_Pending</fullName><default>false</default></value>
  </valueSetDefinition>
</valueSet>

Keep restricted picklists in sync
Audit restricted picklist values across environments so source and target orgs allow the same set.
Update dependent test data
After a field type change, update any Apex test data or formula fields that assumed the old type.

In practice

How Serpent prevents this

Serpent AI's environment diff shows exactly which picklist values exist in one org and not the other, before a deployment ever runs. See the Salesforce deployment error library.

Metadata and data in one deployment flow in Serpent

Prevention

Version-control picklist value sets like any other metadata

Retrieve and commit GlobalValueSet and field metadata changes through the same source control workflow as Apex, instead of editing values ad hoc in Setup.

Bundle a picklist value with the code or test that first uses it

Ship the new value in the same deployment as the class, trigger, or test referencing it, so the two never land out of order.

Review restricted-picklist changes for downstream impact

Before restricting a picklist further, search for Apex, Flow, and integrations that write values the restriction would newly reject.

Common questions

FIELD_INTEGRITY_EXCEPTION, answered

How do I find out which picklist value is missing?

The error text usually names the field and the offending value directly. Compare that field's value set between the source and target org to confirm the gap.

Does this ever fire on a non-picklist field?

Yes, less commonly. It can also fire on type mismatches after a field conversion, or on other platform-level value constraints outside picklists specifically.

Do record-type picklist value mappings deploy automatically with the picklist value?

Not always. Adding a value to a global value set doesn't automatically make it available on every record type; the record type's value mapping metadata often needs its own explicit update.

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

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

Start free Book a demo