How to Write Salesforce Validation Rule Error Messages Users Can Act On
Most Salesforce admins spend their time on the validation rule formula and almost none on the error message. But the formula is something you test once. The message is something every user reads, every time the rule fires.
This guide covers only the message: what Salesforce recommends, why the message can end up somewhere you did not expect, and a simple pattern for writing messages people can act on. For the formulas themselves, see our 10 validation rule examples every admin should know.
What Salesforce says an error message should do
Salesforce defines the Error Message field as "the message that displays to the user when a field fails the validation rule." Its Trailhead guidance adds that messages "should be concise and tell the user exactly what caused the rule to be triggered and what needs to be done to fix the error."
Salesforce's tips for writing validation rules give two more instructions:
- "Give instructions that tell the user the type of entry that's valid, such as Close Date must be after today."
- "Include the field label to identify the field that failed validation, especially if the error message appears at the top of the page."
Field or top of page: where the message appears
When you create a rule you choose an error location: next to a specific field, or at the top of the page. Salesforce recommends the field where possible, because with a field-level error "Salesforce provides a link in the error message that allows the user to quickly jump to the field in question."
But the location you choose is not guaranteed. Salesforce documents three cases where it changes:
| Situation | What happens |
|---|---|
| The chosen field is later deleted, made read only, or removed from the page layout | Salesforce "automatically changes the location to Top of Page" |
| The rule is set to Top of Page and the user is in Lightning Experience | The message appears "at the bottom of the page in Lightning Experience" |
| The rule is on case milestones or Ideas | Messages "can only be displayed at the top of the page" |
This is the main reason to name the field in every message. If someone edits a page layout later, a message written for a highlighted field can end up on its own, with nothing pointing to the problem.
A simple pattern for every message
Write each message in this order:
- Name the field using the label the user sees.
- State the valid entry, not what was wrong.
- Add the fix if the valid entry does not make it obvious.
- Add an error code in brackets so you can find the rule later.
Keep it short. The Tooling API reference states the error message "must be 255 characters or less," so one or two sentences is the right size.
Before and after examples
| Weak message | Better message |
|---|---|
| Please correct the highlighted field. | Close Date must be today or later. [OPP001] |
| Invalid value. | Discount (%) must be between 0 and 30. Ask your manager for larger discounts. [OPP002] |
| This field is required. | Service Start Date is required when Status is Active. [CON004] |
| Error: dates. | Service Start Date must be on or after Contract Date. [CON005] |
The better versions still make sense if they appear at the top of the page with nothing highlighted.
Why add an error code
Trailhead recommends including a code because "this error code helps you find the validation rule if a user contacts you asking for help." Its own example is "When the stage is Qualification or higher, you must enter an amount. [OPP003]".
When a user sends you a screenshot, you search for the code and open the right rule straight away, instead of guessing between dozens of rule names. Use a short prefix per object, such as OPP for opportunities and CON for contracts, and number them as you go.
Common mistakes
- One rule checking two things. Trailhead notes a combined rule "can't tell the user if one or both fields need values" and recommends you "split these two requirements into individual validation rules." If your message needs the word "or", consider two rules.
- Messages only in English for a multilingual team. "To translate error messages, use the Translation Workbench."
- Relying on the highlight. Always name the field, even when the location is a field.
- Long explanations. The policy behind the rule belongs in documentation, not the error.
Try it in a free org
In a free Developer Edition org, create a validation rule with its error location set to a field and trigger it. Then remove that field from the page layout and trigger it again. You will see the same message without its field link, which shows why naming the field matters.
Related reading
- Before You Add a Custom Field in Salesforce: a checklist that pairs well with this guide when a new field needs a rule.
- What does a Salesforce admin do?: where validation rules fit into the daily job.
- Our Substack post Your Error Message Will Not Stay Where You Put It is a shorter read on the same idea.
Frequently asked questions
What makes a good Salesforce validation rule error message? It names the field, states what a valid entry looks like, says how to fix it if that is not obvious, and stays within one or two sentences.
Should I show the error at the field or at the top of the page? At the field where possible, because Salesforce adds a link to jump to it. Still name the field in the text, because the location can change.
Why did my error message move to the top of the page? Salesforce changes the location to Top of Page if the field is deleted, made read only, or is not visible on the page layout.
How long can a validation rule error message be? Up to 255 characters.
Blazer2Role helps career changers move into Salesforce roles, and we sell coaching and courses. Platform behavior varies by edition and changes over time, so check current Salesforce documentation for your org. Drafted with AI assistance under Blazer2Role's editorial direction.