Review incompatible guarded scripts

Yokohama API Reference

Release

yokohama

ft:locale

en-US

ft:publication_title

Yokohama API Reference

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

Review and update scripts incompatible with guarded script

Release version: Yokohama

Updated June 9, 2026

5 minutes to read

Review scripts that are incompatible with guarded script and either rewrite them to use supported features or create an exemption for scripts that can't be rewritten.

Before you begin

Role required: guarded_script_admin or admin

About this task

Guarded script detects and records scripts that use unsupported JavaScript features in the Incompatible Guarded Scripts list when transactions calling those scripts are sent to the server.

Note:

When guarded script is in Phase 1: Detection, scripts sent from authenticated users are recorded in the Incompatible Guarded Scripts list only if they have incompatible syntax. Scripts with incompatible APIs aren't recorded until Phase 2: Syntax enforcement. For information about JavaScript features and APIs supported by guarded script, see JavaScript features supported by guarded script and JavaScript APIs supported by guarded script.

From the Incompatible Guarded Scripts list, analyze each incompatible script and determine an appropriate remediation approach. Consider the following factors when analyzing scripts:

Complexity of the script logic
Frequency of script execution
Business criticality of the functionality
Feasibility of rewriting using supported guarded script features

For additional information about remediating scripts, see the Server-Side Sandbox Runtime Replacement [KB2944435] article on the Now Support Knowledge Base.

Automatic exemptions are created for incompatible scripts sent by authenticated users and detected during Phase 1: Detection and Phase 2: Syntax enforcement. To further secure your instance, you can still review any scripts that have automatic exemptions, update them to be compatible with guarded script, and then remove the exemptions. For more information about automatic exemptions, see Guarded script enforcement.

Procedure

Navigate to All > System Diagnostics > Guarded Script > Incompatible Guarded Scripts.

The list contains the following fields.

Table 1. Incompatible Guarded Scripts list
Field	Description
Is Authenticated	Whether the script was sent by an authenticated user or unauthenticated (guest) user.
Occurrence count	The amount of times that the script has been encountered.
Exemption	A reference to an exemption record if an exemption has been created for the script.
Normalized script	The script source in normalized form. Scripts with the same logic and authentication type are normalized into a single record in the list. For example, scripts sent by guest users that contain `gs.daysAgoStart(7)` or `gs.daysAgoStart(30)` would be normalized into a single record in the list.
Page Title	The endpoints of the transactions that sent the script. For transactions where a page title isn't applicable, the script name is used, such as with a scheduled job.
Scope	The scopes in which the script ran.
Stack trace	The JavaScript stack trace captured the first time that the script was recorded by guarded script.

For each script in the list, select a remediation approach.

Note:

In addition to recording incompatible scripts, guarded script logs errors for rejected scripts. To identify rejected scripts, navigate to System Logs > System Log > Errors with the following message: KittyScript validation failed for <script name> with error: <error message> Source code: <script source>. Use the script name and source code in the error message to locate the corresponding entry in the Incompatible Guarded Scripts list.

Option Steps

Move complex logic to a script include

Option	Steps
Move complex logic to a script include	For scripts that contain complex logic and can be rewritten, move the logic to a script include. Script includes run outside of the sandbox so they can use all features supported by the JavaScript engine. Remove complex logic from the script. Create a script include that includes the removed code. On the Script Include form, select Sandbox enabled. Update the original script to call the new script include using a simple function call, such as `MyScriptInclude.function()`. For more information about creating script includes, see Script includes. You can test updated scripts by running them from the Scripts - Background module with Execute in sandbox? selected. For more information, see Scripts - Background module.
Create an exemption	For scripts that can't be rewritten and are business-critical, create an exemption. Exempt scripts are routed to the script sandbox evaluator instead of the guarded script evaluator. For more information, see Script sandbox evaluator. Warning: Exemptions bypass the enhanced security provided by the guarded script evaluator and should be used sparingly. From the Incompatible Guarded Scripts list, select a script. Select Add Exemption. The exemption applies to every runtime variation of scripts that normalize to the same form with the same authentication type. You can deactivate or delete an exemption by opening an Incompatible Guarded Scripts record and navigating to the Guarded Script Exemptions related list or by navigating to All > System Diagnostics > Guarded Script > Guarded Script Exemption. Note: Exemptions aren't tracked in update sets. To move exemptions between instances, you must manually export and import them.

For scripts that contain complex logic and can be rewritten, move the logic to a script include. Script includes run outside of the sandbox so they can use all features supported by the JavaScript engine.

Remove complex logic from the script.
Create a script include that includes the removed code.
On the Script Include form, select Sandbox enabled.
Update the original script to call the new script include using a simple function call, such as MyScriptInclude.function().

For more information about creating script includes, see Script includes. You can test updated scripts by running them from the Scripts - Background module with Execute in sandbox? selected. For more information, see Scripts - Background module.

Create an exemption

For scripts that can't be rewritten and are business-critical, create an exemption. Exempt scripts are routed to the script sandbox evaluator instead of the guarded script evaluator. For more information, see Script sandbox evaluator.

Warning:

Exemptions bypass the enhanced security provided by the guarded script evaluator and should be used sparingly.

From the Incompatible Guarded Scripts list, select a script.
Select Add Exemption.

The exemption applies to every runtime variation of scripts that normalize to the same form with the same authentication type.

You can deactivate or delete an exemption by opening an Incompatible Guarded Scripts record and navigating to the Guarded Script Exemptions related list or by navigating to All > System Diagnostics > Guarded Script > Guarded Script Exemption.

Note:

Exemptions aren't tracked in update sets. To move exemptions between instances, you must manually export and import them.

Rewriting a script to use a script include

Before After

Before	After
The Incompatible Guarded Scripts list includes the following script because it uses a variable and conditional logic: `var priority = current.priority; if (priority == 1) { gs.beginningOfToday(); } else { gs.endOfLastWeek(); }`	Move the complex logic from the original script to a script include: `var MyDateHelper = Class.create(); MyDateHelper.prototype = { initialize: function() {}, getRelevantDate: function(priority) { if (priority == 1) { return gs.beginningOfToday(); } else { return gs.endOfLastWeek(); } }, type: 'MyDateHelper' };` Then, update the original script to use only a simple expression calling the script include so it's compatible with guarded script: `new MyDateHelper().getRelevantDate(current.priority)`

The Incompatible Guarded Scripts list includes the following script because it uses a variable and conditional logic:

var priority = current.priority;
if (priority == 1) {
    gs.beginningOfToday();
} else {
    gs.endOfLastWeek();
}

Move the complex logic from the original script to a script include:

var MyDateHelper = Class.create();
MyDateHelper.prototype = {
    initialize: function() {},
    getRelevantDate: function(priority) {
        if (priority == 1) {
            return gs.beginningOfToday();
        } else {
            return gs.endOfLastWeek();
        }
    },
    type: 'MyDateHelper'
};

Then, update the original script to use only a simple expression calling the script include so it's compatible with guarded script:

new MyDateHelper().getRelevantDate(current.priority)

What to do next

Monitor the Incompatible Guarded Scripts list regularly to identify any scripts that may need remediation. The list is updated when transactions calling those scripts are sent.