Troubleshoot with Show Diagnostics
Find out why a Record Health Check card shows an unexpected result, an error, or nothing at all. Start from the message on the card. When that is not enough, turn on Show Diagnostics to see the Reason Code, timing, and a diagnosis on the card, and a detailed report in the browser console.
Show Diagnostics only adds information for authorized users. It does not save anything, change records, or grant access. Turn it off when the investigation is finished.
Start with what the card shows
Section titled “Start with what the card shows”The card shows a setup or access message
Section titled “The card shows a setup or access message”When the card cannot load, it shows a title and a message instead of results:
| Card message | Cause | Fix |
|---|---|---|
| This Record Health Check hasn’t been configured for this page. | No Check Set is selected on the component. | In Lightning App Builder, select a Check Set on the component. |
| The selected Record Health Check is no longer available. | The selected Check Set was deleted or renamed. | Select an existing Check Set on the component. |
| This Record Health Check is currently inactive. | The selected Check Set is not active. | Select Active on the Check Set, or select another Check Set. |
| This Record Health Check isn’t configured for this type of record. | The Check Set’s Record Object API Name differs from the page’s object. | Select a Check Set for this object. |
| This Record Health Check doesn’t contain any active Checks. | Every Check in the Check Set is inactive. | Activate at least one Check. |
| No Checks were run. | The Check Set has more than 25 active Checks. | Reduce the Check Set to 25 active Checks. |
| Record Health Check has Check Sets for this record type, but none are active. | The object has Check Sets, but none is active. | Activate a Check Set and select it on the page. |
| No Record Health Check has been created for this record type. | The object has no Check Sets. | Create and activate a Check Set for the object. |
| This component only works on a supported record page. | The component is on a page with no record. | Place it on a record page. |
| This Record Health Check has a configuration problem. | The Check Set or a Check has invalid settings. | Run Validate configuration and fix each error. |
| You don’t have access to view or run Record Health Check. | The user has no Record Health Check permission set. | Assign Record Health Check Card User or Record Health Check User. |
| Record Health Check can’t access the current record. | The user cannot read the record. | Check the user’s sharing and object access. |
| The current record is no longer available. | The record was deleted. | Return to the record list. |
| We couldn’t load Record Health Check. / We couldn’t verify this Record Health Check’s setup. | An unexpected error occurred while loading. | Select Try Again. If it continues, read the administrator detail described below. |
| Record Health Check returned an unexpected response. | The server’s answer could not be read. | Select Try Again. If it continues, read the administrator detail described below. |
Users with diagnostics access also see an Administrator detail line and a Diagnostic ID under the message when they are available, even when Show Diagnostics is cleared.
The card shows a result you did not expect
Section titled “The card shows a result you did not expect”Each row shows one Check’s result:
| Row label | Status | Meaning | What to check |
|---|---|---|---|
| Pass | PASS | The record meets the requirement. | The Check’s configuration, if the requirement itself is wrong. |
| Failed, Warning, or Info | FAIL | The record does not meet the requirement. The label is the Check’s Failure Severity. | Found and Expected values, the operator, and the record’s data. |
| Skipped | SKIPPED | The Check did not apply to the record. | Applies To, the Prerequisite Check, and empty-result settings. |
| Unable to Check | UNABLE_ | Access, configuration, or data prevented a reliable answer. | The user’s access to the fields and objects the Check reads. |
| System Error | ERROR | An unexpected problem stopped the Check. | The diagnosis, with Show Diagnostics on. |
A FAIL is a normal business result, not a defect. SKIPPED and UNABLE_TO_EVALUATE are not
failures; each needs a different fix. See Result labels and statuses.
Choose where to look next
Section titled “Choose where to look next”| Situation | Go to |
|---|---|
| The card has no Run or Rerun button | Run Button Display and Card Heading Display on the Check Set. Hide removes the button. |
| One user gets a different result than another | Compare two users |
| The card and a Flow or async job disagree | Troubleshoot execution context |
A Flow action returns Success false | Flow action error types |
| An Apex call or async job fails | Salesforce debug logs |
| An expected Platform Event does not arrive | Decide when to use Platform Events |
| Any other row result needs explanation | Turn on Show Diagnostics |
Turn on Show Diagnostics
Section titled “Turn on Show Diagnostics”Two settings are needed. Either one alone shows nothing extra.
- Select Show Diagnostics on the Check Set. In Setup, open Custom Metadata Types → Record
Health Check Set → Manage Records, edit the Check Set that the card uses, select Show
Diagnostics (
ShowDiagnostics__c), and save. - Give the viewing user diagnostics access. In Setup, open Permission Sets → Record Health Check Diagnostics Viewer → Manage Assignments, and add the user. Record Health Check Admin also gives diagnostics access.
- Reload the record page, and select Run or Rerun. Diagnostic details appear when the run finishes.
The permission set assignment must be direct and active. Record Health Check does not accept:
- an assignment through a Permission Set Group;
- a clone or copy of the permission set; or
- an assignment that has expired.
Record Health Check Diagnostics Viewer grants diagnostics access only; it cannot run Checks. Assign it together with Record Health Check Card User or Record Health Check User. Reserve Record Health Check Admin for people who maintain Check configuration.
Requiring both settings keeps technical detail away from everyday users: the Check Set setting chooses where details can appear, and the assignment chooses who sees them.
| Permission set | API name | Runs Checks | Gives diagnostics access |
|---|---|---|---|
| Record Health Check Card User | rhc_ | On the card only | No |
| Record Health Check User | rhc_ | Yes | No |
| Record Health Check Admin | rhc_ | Yes | Yes |
| Record Health Check Diagnostics Viewer | rhc_ | No | Yes |
Diagnostics access never adds record or field access. Record Health Check still reads data with the user’s own access.
What appears on the card
Section titled “What appears on the card”With both settings in place, after a run finishes:
| Element | What it shows |
|---|---|
| Gray line under each result | Status, Reason Code, duration, and Evaluation Type, such as UNABLE_. |
| Issue, Where, Why | For UNABLE_ and ERROR results, a short diagnosis: what failed, where it failed, and the likely cause. |
| Inactive count | A summary pill such as 2 Inactive, with a tooltip that names the inactive Checks. |
| Console hint | “For details about all issues, open Developer Tools (F12) and select Console.” |
Users with diagnostics access also see a Formula Check’s pass condition as its Expected value, even when Show Diagnostics is cleared. Other users do not see the formula; they see the Check’s messages.
What appears in the browser console
Section titled “What appears in the browser console”- Open the record page with the card.
- Open the browser’s developer tools: press F12 on Windows or Linux, or Command+Option+I on macOS. Select Console.
- Select Run or Rerun on the card, and wait for the run to finish.
- Find the group named
[RHC] <Check Set Qualified API Name> · <counts>, for example[RHC] Account_Data_Quality · 3 Passed, 1 Failed, 1 Unable · 412ms total.
The group contains:
| Entry | Content |
|---|---|
Run ID | The run’s ID. Use it to find the same run in debug logs and Platform Events. |
Next: lines | What to investigate, in order: System Errors first, then Unable to Check, Failed, and Skipped results. |
[RHC] Results needing review (N) | One collapsed group for each result that is not PASS, ordered ERROR, UNABLE_, FAIL, SKIPPED. When every Check passes, a single line says no diagnostic issues were found. |
| Each result’s group | Status, Severity, Reason code, Evaluator, Duration, and the Issue, Where, Why, Fix, and Verify lines when available. |
Advanced diagnostics | For UNABLE_ and ERROR only: the Check’s configuration, the values and sources it used, the server diagnosis, and the complete result. |
Support report for this check | For UNABLE_ and ERROR only: a self-contained report with the Run ID, user ID, record ID, Check Set, and Check details. |
For a FAIL or SKIPPED result, the Issue, Why, and Fix lines are usually enough: correct the
record’s data, Applies To, or the prerequisite. For UNABLE_TO_EVALUATE or ERROR, read the
Fix and Verify lines first, and expand Advanced diagnostics only when they are not enough.
For a query that runs once per record, Advanced diagnostics shows the query as it ran. Its
LIMIT is Max Query Rows plus 1, because Record Health Check reads one extra row to detect
when the maximum is exceeded.
Advanced diagnostics and the support report can contain record and user IDs, queries, field values, and customer data. Review and remove that information before you share either one.
The support report includes a Diagnostic ID. When Publish Error Log Event is selected on the Check Set, the same ID appears in the Structured Diagnostic Details of the matching Log event.
Compare two users
Section titled “Compare two users”When one user gets PASS and another gets UNABLE_TO_EVALUATE or a different answer, the cause
is almost always access. Record Health Check reads every record and field with the running user’s
access.
- Confirm that both users have a runner permission set: Record Health Check Card User for the card, or Record Health Check User for the card, Flow, and Apex.
- Compare their object and field permissions for every field the Check reads, including fields in formulas and queries.
- Compare their access to the record and to the related records the queries read, including sharing, restriction rules, and scoping rules.
- Turn on Show Diagnostics, give the affected user Record Health Check Diagnostics Viewer temporarily, and read the Reason Code on the affected user’s card.
- Remove the temporary assignment when you are finished.
A result as a System Administrator does not show what other users see: an administrator can usually read every record and field.
Collect evidence for support
Section titled “Collect evidence for support”Gather one consistent set of evidence:
- the package version, such as 2.0.11.4, and the org type;
- what started the run (the card, a Flow, Apex, or an async job), the user, and the exact time with its time zone;
- the Check Set and Check Qualified API Names and the record’s object;
- the Run ID, the Diagnostic ID, the status, the Reason Code, and the message on the card;
- the reviewed support report from the console; and
- the smallest configuration that reproduces the problem.
Remove record IDs, user IDs, org IDs, customer data, session IDs, access tokens, and passwords from screenshots and console output before sharing them. Report security vulnerabilities privately through the security policy, never in a public issue.
Turn diagnostics off
Section titled “Turn diagnostics off”- Clear Show Diagnostics on the Check Set.
- Remove temporary Record Health Check Diagnostics Viewer or Record Health Check Admin assignments.
- Reload the record page and confirm that the gray lines and the console hint no longer appear.