FIELD_CUSTOM_VALIDATION_EXCEPTION in an Apex test on deploy

Why did a validation rule fail a test I did not touch?

A test tried to insert or update a record, and a validation rule said no. The part after the status code is the error message you wrote on the rule, so the message names the rule's intent even when it does not name the rule.

Your test data is older than the rule. This is why the same deploy can pass in a sandbox that has the rule inactive and fail in production where it is active.

Which tests does a new validation rule break?

• You deployed a new validation rule with metadata that already contains tests inserting records the rule now rejects. Tests across the org break at once, not only the one you touched.
• A required-field rule was added to a standard object, and old tests build an Account or Contact with only a Name.
• The test inserts a User or a record owned by one, and the rule checks a profile, role or field that the test user does not have.
• Sandbox and production disagree. The rule is active in one and inactive in the other.

One Stack Exchange answer says to deactivate the rule in both orgs, deploy, and turn it back on. The poster calls it probably not best practice, and we agree (question 25074). It works in a pinch. It also leaves a window where bad data can get in.

What does the failure look like in a deploy?

A validation rule on Account with the formula ISBLANK(Phone) and a test that inserts new Account(Name = 'Acme Test'), validated with a check-only deploy:

AccountSeedTest.insertsAccount
System.DmlException: Insert failed. First exception on row 0; first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, Phone is required on every account.: []
Class.AccountSeedTest.insertsAccount: line 4, column 1

The text before : [] is the rule's error message. Search Setup > Object Manager > Account > Validation Rules for that wording to find the rule.

How do I fix it in Setup?

1. Copy the error message text from Setup > Deployment Status > View Details.
2. Find the rule: Object Manager, pick the object, Validation Rules. Open it and read the formula.
3. Update the test to create valid data. In the example, add Phone = '555-0100'. Build the records in one shared test data factory class so the next rule only needs one fix.
4. If the rule only applies to people and not to automation, add a bypass condition such as $Permission.Bypass_Validation to the formula and give that custom permission to the test through a permission set assignment. Use this sparingly, since it adds a path around your own rule.
5. Run the test in the sandbox with the rule active before you validate again.

How do I fix it with the CLI?

sf apex run test --class-names AccountSeedTest --result-format human --wait 10 -o <sandbox-alias>
sf project deploy start --dry-run --source-dir force-app --test-level RunSpecifiedTests --tests AccountSeedTest -o <target-alias>

How do I roll out a validation rule without breaking tests?

Treat a new validation rule as a change to every test that touches the object. Before you deploy the rule, search your Apex for insert and new Account( on that object. Keep test records in a factory so there is one place to update. Activate the rule in the sandbox first and run all local tests there, so you find the broken ones before production does.

Salesforce recommends that tests create their own data (Apex Developer Guide). That helps here, because your factory is also the single place the rules get respected.

Clientell AI lists the validation rules related to a proposed change and runs the covering tests before you approve. See AI Salesforce deployments. The validation rule glossary entry explains how rules evaluate.

Other test-time failures: coverage below 75%, assertion failed, trigger exception, callout in a test.