Skip to content
Suggest a correction

Platform limitations and safe patterns

Reference11 min read

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.

These limits are fixed in the package. Limits on the length of saved text fields are in Field limits.

LimitValueWhen it is exceeded
Active Checks in one Check Set25A 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_MAX_CHECKS_EXCEEDED. A request for one named Check still runs
Unique records in one Apex request or Flow group200Apex throws MAX_RECORDS_PER_SCOPE_EXCEEDED; Flow returns Error Type VALIDATION
Records in one packaged Batch or Scheduled job2,000, run in transactions of at most 200The job is rejected before it is submitted. Write your own Batch class for more records
Records in one packaged Queueable job200The job is rejected before it is enqueued
Groups in one Flow action call10Every input in the call returns Error Type LIMIT
Result JSON in one Flow action call2,000,000 charactersThe remaining inputs return Error Type LIMIT
Salesforce formula evaluations in one transaction95, shared by every request in the transactionA 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 200ROW_LIMIT_EXCEEDED; in a multi-record run the limit covers the combined query, which returns SCOPE_ROW_CAP_EXCEEDED. See Bulk query grammar
Merge tokens in one template100UNABLE_TO_EVALUATE with TOKEN_LIMIT_EXCEEDED
Completed message or display text20,000 charactersUNABLE_TO_EVALUATE with RESOLVED_TEMPLATE_TOO_LONG; the text is never shortened
Completed Action URL2,000 charactersThe link is removed; the Fix Message still shows
Inline links in one display field100Configuration validation reports INLINE_LINK_LIMIT_EXCEEDED
Relationships in one record merge-token path5UNKNOWN_TOKEN_PROPERTY
Calculated-formula dependency chain10 levelsUNABLE_TO_EVALUATE with FORMULA_DEPENDENCY_DEPTH_EXCEEDED
Check evaluations the card runs at once8, shared by every card on the pageFurther Checks wait for a free slot
Values shown in a Found or Expected list10The rest are still compared but not shown
Record IDs in one Preview200 uniqueThe Preview request is rejected
Qualified API Name of a requested Check or Check Set255 charactersThe 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 class1 to 80 charactersThe 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.

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 boundaryCeilingWhen exceeded
{!record.Parent...} merge path5 relationship hopsToken validation/resolution fails; fallback is only for an optional value, not an invalid path
Calculated-formula dependency expansion10 expansionsUNABLE_TO_EVALUATE / FORMULA_DEPENDENCY_DEPTH_EXCEEDED
Salesforce cross-object formula spanningSalesforce 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.

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 shapePackaged exampleSafe pattern when it must count
WhatId = Account.IdCountedUse the packaged Apex Check
Contact WhoId, null WhatIdNot countedResolve Contacts for scoped Accounts, then query activity by WhoId in Apex
Lead WhoIdNot Account activityEvaluate the Lead directly
TaskRelation / EventRelationNot countedUse an org-specific, feature-aware Apex plugin
Opportunity/Case WhatIdNot countedDeliberately 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.

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 conceptPerson Account counterpartGuidance
BillingStreet/City/...PersonMailingStreet/City/...Use explicit applicability
Contact EmailAccount PersonEmailDo not infer PA completeness from Contact count
Website, IndustryOften not meaningfulGate B2B checks with NOT(IsPersonAccount)
ParentId hierarchyUsually business-onlyMark hierarchy checks business-only
Contact identityPersonContactIdUse 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.

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.

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() or TODAY() 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 evidenceRecommended Check designSafe stale or unknown outcome
Stored calculation timestamp and source LastModifiedDateFormula or Compare Two Queries compares the two timestampsFAIL when the source is newer; never infer freshness from the derived value alone
Stored watermark and maximum permitted ageFormula compares the watermark with NOW() or TODAY() using the intended timezone/date boundaryFAIL outside the threshold; missing watermark follows an explicit applicability or prerequisite policy
Child or aggregate source changesQuery or Compare Two Queries obtains a source maximum/change signal and compares it with the watermarkA cap, inaccessible source, or unprovable unit returns unable rather than a partial PASS
Processing job history or external provenanceReviewed subscriber Apex reads the authorized evidence and returns one outcome per root record within the documented limitsMissing, 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.

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 ROWS is rejected, so recycle-bin rows are invisible. Restore a row or use purpose-built administrative Apex when deleted records matter.
  • WITH SECURITY_ENFORCED is rejected with INVALID_SOQL_TEMPLATE. Record Health Check adds WITH USER_MODE to every query itself.
  • WITH DATA CATEGORY is rejected with UNSUPPORTED_BULK_QUERY_SHAPE because it cannot be safely combined with WITH USER_MODE. Use an Apex Check designed for Knowledge categories.
  • File-link queries require org validation because ContentDocumentLink applies 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 AccountContactRelation by AccountId. A role-presence recipe is SELECT 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.