Skip to content
Suggest a correction

Save or route restricted errors

Guide7 min read

Keep a record of the technical errors Record Health Check encounters, so support staff can investigate them after Salesforce debug logs are gone, by receiving the Record Health Check Log Platform Event. When a Check Set allows it, Record Health Check publishes one Log event for each error it captures; a restricted Platform Event-triggered Flow or Apex trigger saves it.

Log events can contain record IDs, user IDs, error messages, and stack traces. Use them only for technical support. Business automation that reacts to FAIL, UNABLE_TO_EVALUATE, or ERROR results should use the Record Health Check Result event, which contains no technical details.

Setup valueValue
Platform Event labelRecord Health Check Log
API name in your orgrhc__Record_Health_Check_Log__e
Publish behaviorPublish Immediately

Every field name carries the rhc__ prefix in your org. See the Log field reference for every field.

FieldAPI name in your orgValue
Event IDrhc__EventId__cA different value for every event. Use it to detect a repeated event.
Run IDrhc__RunId__cThe run in which the error happened.
Levelrhc__Level__cERROR.
Coderhc__Code__cA short classification of the error, such as BATCH_SCOPE_FAILED.
Check Set Developer Namerhc__CheckSetDeveloperName__cThe Check Set that was running, when known.
Check Developer Namerhc__CheckDeveloperName__cThe Check that was running, when known.
Record IDrhc__RecordId__cThe record being checked, when known.
User IDrhc__UserId__cThe user who ran the Checks.
Exception Typerhc__ExceptionType__cThe Apex exception type, when an exception caused the error.
Messagerhc__Message__cThe exception message and error details, up to 4,000 characters.
Structured Diagnostic Detailsrhc__DetailsJson__cThe same details as JSON, up to 4,000 characters.
Stack Tracerhc__StackTrace__cThe Apex stack trace, up to 32,000 characters.
Occurred Atrhc__OccurredAt__cWhen the error was captured.
Contract Versionrhc__ContractVersion__c1.0, the version of the event’s shape.

Codes lists every Code in this release and what each one means. Codes can change between releases. Use them to group errors, and send any Code the automation does not recognize to review rather than failing.

Log publication is off by default. Two settings are needed, and both are independent of the card publication checkboxes and of Event Publication:

  1. In Setup, open Custom Metadata Types → Record Health Check Set → Manage Records, edit the Check Set, and select Publish Error Log Event.
  2. Assign the Record Health Check Error Log Publisher permission set to each user who runs that Check Set, including the users who start Flows and the users who run async jobs. When Salesforce rejects a Log event, the debug log shows LOG_EVENT_PUBLISH_FAILED or LOG_EVENT_FLUSH_FAILED, and the Check result does not change.

The permission set grants Create and Read access to the Log event. Salesforce requires Read with Create, so every assignee can read restricted error details; assign it only to users trusted with them.

When the setting is selected, every error Record Health Check captures while running that Check Set publishes a Log event, whether the card, a Flow, Apex code, or an async job started the run. Clearing the setting does not affect Salesforce debug logs, which still record the same errors while debug logging is on.

Every Unable to Check and System Error result counts as an error and can publish a Log event with Code DIAGNOSTIC_INCIDENT. Estimate the volume before you select the setting on a Check Set that runs for many records.

Before you build receiving automation, agree on:

  • who can read the event, the saved errors, and the reports on them;
  • which fields to save; for counts and trends, Code and the developer names are enough;
  • how long saved errors are kept; and
  • which destinations must never receive messages or stack traces, such as broad email lists or chat channels.

Create a custom object owned by your team, such as Record Health Check Error (Record_Health_Check_Error__c). Record Health Check does not create it. Make it Private, and give access only to support staff through a permission set your organization owns.

Error fieldAPI name used belowSuggested typeEvent field
Event IDEvent_Id__cText(80), Uniquerhc__EventId__c
Run IDRun_Id__cText(120)rhc__RunId__c
Occurred AtOccurred_At__cDate/Timerhc__OccurredAt__c
CodeCode__cText(120)rhc__Code__c
Check Set Developer NameCheck_Set_Developer_Name__cText(120)rhc__CheckSetDeveloperName__c
Check Developer NameCheck_Developer_Name__cText(120)rhc__CheckDeveloperName__c
Salesforce Record IDSalesforce_Record_Id__cText(18)rhc__RecordId__c
User IDUser_Id__cText(18)rhc__UserId__c
Exception TypeException_Type__cText(120)rhc__ExceptionType__c
MessageMessage__cLong Text Area(32768)rhc__Message__c
Stack TraceStack_Trace__cLong Text Area(32768)rhc__StackTrace__c
Contract VersionContract_Version__cText(10)rhc__ContractVersion__c

Message and Stack Trace are optional. When you save them, restrict their field-level security and every report, export, and backup that includes them.

  1. In Setup, open Flows, select New Flow, and choose Platform Event—Triggered Flow.
  2. Select Record Health Check Log as the Platform Event.
  3. Add a Decision element. When {!$Record.rhc__ContractVersion__c} does not equal 1.0, send the event to review and end the Flow.
  4. Add a Get Records element for Record Health Check Error where Event ID equals {!$Record.rhc__EventId__c}. Store only the first record.
  5. Add a Decision element. When the record from step 4 exists, end the Flow.
  6. Add a Create Records element that saves the error with the approved fields.
  7. Optionally, notify a restricted support queue. Include the Code and the Run ID, not the message or stack trace.
  8. Connect each fault path to monitoring that does not run Record Health Check.
  9. Test with a sandbox error, and then activate the Flow.

The Flow must never run Record Health Check. An error in that run could publish another Log event and start the Flow again.

This example saves the identifying fields and the Code. Add Message or Stack Trace only after your access and retention review.

trigger HealthCheckErrorTrigger on rhc__Record_Health_Check_Log__e(
after insert
) {
HealthCheckErrorHandler.saveErrors(Trigger.new);
}
public with sharing class HealthCheckErrorHandler {
public static void saveErrors(List<rhc__Record_Health_Check_Log__e> events) {
Set<String> eventIds = new Set<String>();
for (rhc__Record_Health_Check_Log__e eventRecord : events) {
eventIds.add(eventRecord.rhc__EventId__c);
}
// Event IDs already saved by an earlier delivery.
Set<String> savedEventIds = new Set<String>();
for (Record_Health_Check_Error__c saved : [
SELECT Event_Id__c
FROM Record_Health_Check_Error__c
WHERE Event_Id__c IN :eventIds
]) {
savedEventIds.add(saved.Event_Id__c);
}
List<Record_Health_Check_Error__c> errors = new List<Record_Health_Check_Error__c>();
for (rhc__Record_Health_Check_Log__e eventRecord : events) {
if (savedEventIds.contains(eventRecord.rhc__EventId__c)) {
continue;
}
// An unexpected event shape goes to review instead of the error object.
if (eventRecord.rhc__ContractVersion__c != '1.0') {
// Send eventRecord.rhc__EventId__c to restricted monitoring.
continue;
}
savedEventIds.add(eventRecord.rhc__EventId__c);
errors.add(
new Record_Health_Check_Error__c(
Event_Id__c = eventRecord.rhc__EventId__c,
Run_Id__c = eventRecord.rhc__RunId__c,
Occurred_At__c = eventRecord.rhc__OccurredAt__c,
Code__c = eventRecord.rhc__Code__c,
Check_Set_Developer_Name__c = eventRecord.rhc__CheckSetDeveloperName__c,
Check_Developer_Name__c = eventRecord.rhc__CheckDeveloperName__c,
Salesforce_Record_Id__c = eventRecord.rhc__RecordId__c,
User_Id__c = eventRecord.rhc__UserId__c,
Exception_Type__c = eventRecord.rhc__ExceptionType__c,
Contract_Version__c = eventRecord.rhc__ContractVersion__c
)
);
}
if (errors.isEmpty()) {
return;
}
List<Database.SaveResult> results = Database.insert(errors, false);
for (Integer i = 0; i < results.size(); i++) {
if (!results[i].isSuccess()) {
// Send errors[i].Event_Id__c and results[i].getErrors() to restricted monitoring.
}
}
}
}

The handler must never call Record Health Check, for the same reason as the Flow. To test it, publish an rhc__Record_Health_Check_Log__e event with Event ID, Run ID, Level, Occurred At, and Contract Version set, call Test.getEventBus().deliver(), and then query the error object.

By default, Salesforce runs Platform Event triggers and Platform Event-triggered Flows as the Automated Process user. To run an Apex trigger as a specific user, configure it with Salesforce’s PlatformEventSubscriberConfig, and give that user Read access to the Log event.

The Log event uses Publish Immediately: Salesforce delivers it even when the transaction that captured the error rolls back. That is what makes errors visible when a failing Check stops a Flow or an Apex transaction.

Record Health Check collects the errors during a request and publishes them, in groups of up to 100, when the request ends. A transaction that stops at an uncatchable Salesforce limit can end before that point, so some errors never produce an event. Keep Salesforce debug logs and your normal Apex exception monitoring for those cases.

Test each of these cases in a sandbox:

  1. An error creates one protected error record.
  2. The same Event ID received twice creates one record and one notification.
  3. An event with a blank Record ID, Check, or Exception Type is saved without a fault.
  4. A Contract Version other than 1.0 goes to review, and an unfamiliar Code is still saved.
  5. The receiving automation never runs Record Health Check.
  6. Users without access cannot read the event, the object, its restricted fields, or its reports.