Platform limitations and safe patterns
Find the Salesforce platform boundaries that affect Record Health Check Checks, such as formula planning, query visibility, polymorphic relationships, currency, and time zones, and the safe pattern for each. For ordinary configuration, start with the Formula or Query reference.
Record Health Check runs inside Salesforce security, query, and formula-evaluation rules. A Check can be valid and still be unable to answer some questions; each section names the boundary and a safe alternative.
Limits at a glance
Section titled “Limits at a glance”These limits are fixed in the package. Limits on the length of saved text fields are in Field limits.
| Limit | Value | When it is exceeded |
|---|---|---|
| Active Checks in one Check Set | 25 | A request for the whole Check Set runs no Checks: the card shows “No Checks were run.”, Flow returns Error Type LIMIT, and Apex throws FRAMEWORK_. A request for one named Check still runs |
| Unique records in one Apex request or Flow group | 200 | Apex throws MAX_; Flow returns Error Type VALIDATION |
| Records in one packaged Batch or Scheduled job | 2,000, run in transactions of at most 200 | The job is rejected before it is submitted. Write your own Batch class for more records |
| Records in one packaged Queueable job | 200 | The job is rejected before it is enqueued |
| Groups in one Flow action call | 10 | Every input in the call returns Error Type LIMIT |
| Result JSON in one Flow action call | 2,000,000 characters | The remaining inputs return Error Type LIMIT |
| Salesforce formula evaluations in one transaction | 95, shared by every request in the transaction | A request that would need more is rejected before any Check runs. A Formula Check uses one per record, and its Display: Found Formula and Display: Expected Formula each add one per record plus seven. An Applies When (Formula) adds one per record on any Check. On a Query Check, Expected Value (Formula) and Value to find in the list (formula) each add one per record, plus seven when Formula Result Type is Automatic |
| Rows returned by one Check query (Max Query Rows) | 1 to 2,000; default 200 | ROW_; in a multi-record run the limit covers the combined query, which returns SCOPE_. See Bulk query grammar |
| Merge tokens in one template | 100 | UNABLE_ with TOKEN_ |
| Completed message or display text | 20,000 characters | UNABLE_ with RESOLVED_; the text is never shortened |
| Completed Action URL | 2,000 characters | The link is removed; the Fix Message still shows |
| Inline links in one display field | 100 | Configuration validation reports INLINE_ |
Relationships in one record merge-token path | 5 | UNKNOWN_ |
| Calculated-formula dependency chain | 10 levels | UNABLE_ with FORMULA_ |
| Check evaluations the card runs at once | 8, shared by every card on the page | Further Checks wait for a free slot |
| Values shown in a Found or Expected list | 10 | The rest are still compared but not shown |
| Record IDs in one Preview | 200 unique | The Preview request is rejected |
| Qualified API Name of a requested Check or Check Set | 255 characters | The request is rejected before any Check runs. Apex throws IllegalArgumentException with Check QualifiedApiName must not exceed 255 characters. or Check Set QualifiedApiName must not exceed 255 characters.; a Flow action returns the same message with Error Type VALIDATION for that input; the Agentforce actions return Check Qualified API Name must not exceed 255 characters. or Check Set Qualified API Name must not exceed 255 characters.; the REST tool returns Qualified API Name has an invalid format or exceeds 255 characters. |
| Job name passed to the packaged Scheduled class | 1 to 80 characters | The schedule is not created: Apex throws IllegalArgumentException with A schedule name of 1–80 characters is required. |
The record-page card checks one record at a time, so the record limits apply to Flow, Apex, and asynchronous runs. Every run also shares the transaction’s Salesforce governor limits, such as queries, query rows, CPU time, and heap, with any other code in the same transaction.
Formula planning and evaluation
Section titled “Formula planning and evaluation”Record Health Check evaluates each formula against the record it loads for the run. When the
formula references a formula field, Record Health Check also loads the fields that formula field
depends on. If that chain of formula fields is more than ten levels deep, the Check returns
UNABLE_TO_EVALUATE with FORMULA_DEPENDENCY_DEPTH_EXCEEDED instead of evaluating incomplete
data. Merge-token paths
have a separate depth contract; see merge tokens.
Roll-up summary fields are different: their queried value is supplied to FormulaEval. Record Health
Check does not reproduce the roll-up query. Boolean false is FAIL; a null or unbuildable result is
UNABLE_TO_EVALUATE.
| Depth boundary | Ceiling | When exceeded |
|---|---|---|
{!record. merge path | 5 relationship hops | Token validation/resolution fails; fallback is only for an optional value, not an invalid path |
| Calculated-formula dependency expansion | 10 expansions | UNABLE_ / FORMULA_ |
| Salesforce cross-object formula spanning | Salesforce compiler limit (commonly 5 levels) | Salesforce rejects the formula at save/compile time |
The dependency ceiling is larger because one formula input can expand through several stored formula
fields. Keep author-written formula and merge paths within five relationship hops. For an optional
parent value within that ceiling, use a literal fallback such as
{!record.Parent.Name fallback="no parent"}.
Formula evaluation treats a blank number as zero. A blank Number field therefore satisfies
NumberOfEmployees = 0. This differs from a Query Check, where If Field Value Is Empty decides
how a blank value compares.
Global merge fields such as $User, $Profile, $Setup, $Permission, and $CustomMetadata
are not record fields. Salesforce formula evaluation rejects them in a formula evaluated against a
record, so a Check that uses one returns UNABLE_TO_EVALUATE with INVALID_FORMULA. Do not use
them in a Pass Condition. When the decision depends on the running user, use a Query or Apex Check
and test it as each kind of user.
Polymorphic relationships
Section titled “Polymorphic relationships”Use colon syntax to state the type: Owner:User.IsActive, Who:Contact.Email, or
Who:Lead.Email. The planner fails closed when a multi-type relationship is ambiguous. Only fields
exposed by Salesforce’s flat polymorphic Name entity can be hydrated without TYPEOF; a type-only
path such as What:Account.Industry requires a Query or Apex Check.
Owner.IsActive loads correctly for active and inactive User owners without TYPEOF. A User-only
formula such as Owner:User.IsActive returns UNABLE_TO_EVALUATE for a record owned by a Queue or
Group. Make the Check’s messages and action links describe the same behavior, and do not build a
link such as /lightning/r/User/{!record.OwnerId}/view unless the owner is always a User.
Activities: What, Who, and shared relations
Section titled “Activities: What, Who, and shared relations”The packaged AccountHasRecentActivityCheck counts completed Tasks and all Events, including
future Events, that are dated on or after the start of its look-back window and whose WhatId is
the Account. It does not count activity related to the Account’s Contacts or child records.
| Activity shape | Packaged example | Safe pattern when it must count |
|---|---|---|
WhatId = Account. | Counted | Use the packaged Apex Check |
Contact WhoId, null WhatId | Not counted | Resolve Contacts for scoped Accounts, then query activity by WhoId in Apex |
Lead WhoId | Not Account activity | Evaluate the Lead directly |
TaskRelation / EventRelation | Not counted | Use an org-specific, feature-aware Apex plugin |
Opportunity/Case WhatId | Not counted | Deliberately roll child activity up in custom Apex |
A safe bulk Who recipe queries Contact(Id, AccountId) once for all Account IDs, queries recent
Task/Event rows by those WhoIds, maps each WhoId back to AccountId, seeds every requested Account
with zero, and ignores keys outside the requested scope. Shared Activities require a separate
feature-aware implementation.
LastActivityDate is Salesforce’s stored activity summary, not completed Task/Event counting. A
Formula Check using it can change for activity the WhatId-only Apex example does not count. When a
New Task action starts from Contact or Person Account context, set the intended WhoId; setting only
WhatId expresses a different relationship.
Person Accounts
Section titled “Person Accounts”Packaged examples do not require Person Account-only fields. Salesforce gives a Person Account one
underlying PersonContact child whose AccountId is the Person Account. Consequently,
COUNT(Contact) WHERE AccountId = current Account returns one for that system-created identity, and
a generic “at least one Contact” Check can vacuously PASS without proving that the account has a
separate business contact. Use explicit Person Account applicability instead of interpreting that
count as relationship coverage.
| Business Account concept | Person Account counterpart | Guidance |
|---|---|---|
BillingStreet/City/. | PersonMailingStreet/City/. | Use explicit applicability |
Contact Email | Account PersonEmail | Do not infer PA completeness from Contact count |
Website, Industry | Often not meaningful | Gate B2B checks with NOT(IsPersonAccount) |
ParentId hierarchy | Usually business-only | Mark hierarchy checks business-only |
| Contact identity | PersonContactId | Use only in PA-enabled org-specific metadata/code |
Business-only recipe: NOT(IsPersonAccount). A PA recipe can use
IsPersonAccount && NOT(ISBLANK(PersonEmail)) in a PA-enabled org, but metadata containing Person*
fields is not portable to an org without the feature. Action links should target Account unless the
implementation deliberately resolves and authorizes PersonContactId.
Currency, dates, and display
Section titled “Currency, dates, and display”Multi-currency support preserves and displays a loaded row’s CurrencyIsoCode; it does not perform
corporate, dated, or Advanced Currency Management conversion. CURRENCYRATE() is not a supported
FormulaEval workaround. Normalize in Query/Apex when cross-currency comparison is required. Display
formatting adds a code/symbol but does not change comparison units.
Currency authoring guards resolve both direct fields and relationship paths through describe
metadata. They apply only in
multi-currency orgs; an aggregate may retain one unit either by grouping on CurrencyIsoCode or by
filtering it to one literal ISO code in a conjunctive outer predicate. Predicates containing OR
or NOT at outer depth do not prove that every contributing row has that unit and are refused;
operators and equalities inside semi-joins do not alter the outer proof.
TODAY(), NOW(), DATEVALUE(), and datetime comparisons follow FormulaEval and the running-user
context. A formatted chip follows display locale/timezone rules and does not prove that the Pass
Condition used the same boundary. Prefer Date fields for date-only SLAs; for datetime cutoffs,
document the timezone and test users on both sides of the boundary.
Derived values, snapshots, and freshness
Section titled “Derived values, snapshots, and freshness”To check whether data is current, use an available timestamp or processing status in a Formula, Query, or custom Apex Check. Choose the acceptable age for your business process.
Record Health Check cannot tell when a stored or derived field was last calculated. Make freshness an explicit part of the Check when the data model exposes evidence for it:
- compare a snapshot timestamp with a source-change timestamp using Formula or Compare Two Queries;
- compare a watermark with
NOW()orTODAY()when policy is based on maximum age; - use applicability or a prerequisite Check to handle a missing or unreadable watermark; and
- use reviewed subscriber Apex when freshness depends on job history or another source that the checked record does not expose.
Snapshot-versus-current value comparison is an authoring decision: Compare Two Queries can report whether the values differ, but it cannot establish which value should govern the decision. A null watermark cannot prove freshness. Record Health Check has no freshness setting of its own: it does not inspect background jobs, trigger recalculation, or treat a copied value as current.
Use the smallest existing mechanism that can prove the policy:
| Available evidence | Recommended Check design | Safe stale or unknown outcome |
|---|---|---|
Stored calculation timestamp and source LastModifiedDate | Formula or Compare Two Queries compares the two timestamps | FAIL when the source is newer; never infer freshness from the derived value alone |
| Stored watermark and maximum permitted age | Formula compares the watermark with NOW() or TODAY() using the intended timezone/date boundary | FAIL outside the threshold; missing watermark follows an explicit applicability or prerequisite policy |
| Child or aggregate source changes | Query or Compare Two Queries obtains a source maximum/change signal and compares it with the watermark | A cap, inaccessible source, or unprovable unit returns unable rather than a partial PASS |
| Processing job history or external provenance | Reviewed subscriber Apex reads the authorized evidence and returns one outcome per root record within the documented limits | Missing, failed, inaccessible, or never-run evidence cannot default to PASS |
The same derived field can legitimately have different freshness policies in different organizations. Keeping those thresholds and evidence paths in Check configuration makes each policy visible and reviewable.
Query and data-model boundaries
Section titled “Query and data-model boundaries”Record Health Check deterministically pre-validates the root object and comma-separated plain field
or relationship paths in a flat SELECT. Missing roots return OBJECT_NOT_RESOLVED; missing fields
and relationships return FIELD_NOT_RESOLVED or RELATIONSHIP_NOT_RESOLVED; user-mode access
remains distinct. Compare Two Queries also validates its configured extraction fields against each
query root before display or comparison. Subqueries, TYPEOF, aggregate expressions and aliases, SOQL functions, date
literals, and bind/syntax errors are outside this schema subset. If those shapes fail at execution,
they return INVALID_SOQL_TEMPLATE; the framework does not build a second SOQL parser or infer a
more specific result from localized platform text.
A resolved Base64/Blob selected field is a deliberately unsupported value boundary and returns
FIELD_TYPE_NOT_SUPPORTED before query execution, comparison, serialization, or display. If binary
inspection is essential, use reviewed user-mode Apex that returns only a redacted business outcome
and never the binary content.
ALL ROWSis rejected, so recycle-bin rows are invisible. Restore a row or use purpose-built administrative Apex when deleted records matter.WITH SECURITY_ENFORCEDis rejected withINVALID_SOQL_TEMPLATE. Record Health Check addsWITH USER_MODEto every query itself.WITH DATA CATEGORYis rejected withUNSUPPORTED_BULK_QUERY_SHAPEbecause it cannot be safely combined withWITH USER_MODE. Use an Apex Check designed for Knowledge categories.- File-link queries require org validation because
ContentDocumentLinkapplies additional implementation restrictions under user-mode SOQL. Use a custom Apex Check unless the exact Query template has passed in a representative org. A Knowledge action URL navigates only; it does not change evaluation semantics. - For indirect Contacts, query
AccountContactRelationbyAccountId. A role-presence recipe isSELECT COUNT() FROM AccountContactRelation WHERE AccountId = {!record.Id} AND IsActive = true AND Roles INCLUDES ('Decision Maker'). Direct Contact (Contact.AccountId), ACR, and OpportunityContactRole are separate relationships; Formula cannot aggregate these child collections. - After duplicate merge, the losing ID no longer identifies the survivor. Rerun against the surviving record; activity WhatIds are evaluated exactly as loaded for that run.
These constraints favor explicit UNABLE_TO_EVALUATE outcomes and narrow recipes over believable
but incorrect PASS/FAIL results.