Troubleshooting SuiteScript 2.1 Migration Issues
When a SuiteScript 2.0 script is updated or tested using SuiteScript 2.1, errors can occur during file upload, script execution, or integration processing. Review the script's @NApiVersion annotation, the script record's Execute As Version field, and any applicable account-level preferences to determine which SuiteScript version is processing the script.
For information about differences, see Differences Between SuiteScript 2.0 and SuiteScript 2.1.
Syntax Errors When Uploading a Script File
A syntax error can occur when you upload a script file that contains SuiteScript 2.1 syntax but is annotated with @NApiVersion 2.0 or @NApiVersion 2.x.
SuiteScript validates the script according to its @NApiVersion value. An account-level preference that executes scripts using the SuiteScript 2.1 runtime does not change validation for a script file that remains annotated as SuiteScript 2.0 or SuiteScript 2.x.
To resolve this error, use one of the following approaches:
-
Update the script's @NApiVersion JSDoc tag to 2.1 if the script is ready to use SuiteScript 2.1.
-
Remove the SuiteScript 2.1 only syntax if the script must remain compatible with SuiteScript 2.0.
A Script Continues to Run as SuiteScript 2.0
If you enabled the Execute SuiteScript 2.0 Server Scripts as SuiteScript 2.1 preference but a script continues to run as SuiteScript 2.0, review the following conditions:
-
The preference affects only eligible server scripts annotated with @NApiVersion 2.0.
-
Script types not supported in SuiteScript 2.1 are not affected by the preference.
-
A script record with the Execute As field set to 2.0 continues to run as SuiteScript 2.0.
Open the script record and review the Execute As Version field to confirm the runtime used for the script.
-
Client scripts are not affected by the server-script preference.
-
A script that NetSuite does not recognize as compatible with SuiteScript 2.1 continues to run as SuiteScript 2.0.
Error Occurs After an Account-Level Preference is Changed
The Execute SuiteScript 2.0 Server Scripts as SuiteScript 2.1 preference is intended for compatibility testing. If a script fails after the preference is enabled, test the script in a sandbox account and identify the SuiteScript 2.1 behavior that caused the failure.
If you must restore SuiteScript 2.0 processing while you investigate the issue:
-
Go to Setup > Company > Preferences > General Preferences.
-
Clear the Execute SuiteScript 2.0 Server Scripts as SuiteScript 2.1 box.
-
Click Save.
Scripts explicitly annotated with @NApiVersion 2.1 continue to run as SuiteScript 2.1 after the preference is cleared.
Runtime Error After Changing Script Version to 2.1
A script can upload successfully but fail at runtime after you change its annotation to 2.1.
SuiteScript 2.1 uses a different runtime engine than SuiteScript 2.0, and some JavaScript behavior differs.
Review the script for the following compatibility issues:
-
Use of reserved words as identifiers.
-
Strict mode behavior.
-
Error object properties.
-
Parsing invalid JSON.
-
Reassignment of
constvariables. -
Use of unsupported
for each...instatement. -
Date formatting with
toLocaleDateString(). -
toSource()method. -
parseInt()behavior. -
Promises in server scripts.
Correct the affected code and test the script again in each supported execution context.
RESTlet Returns an Unexpected Value
RESTlet behavior can differ when a script runs as SuiteScript 2.1. In particular, review RESTlet post input handling and return values.
To troubleshoot a RESTlet:
-
Confirm that the deployed RESTlet is running as the expected SuiteScript version.
-
Test each supported HTTP method with representative request data.
-
Compare the request body and response with the results from the SuiteScript 2.0 version.
-
Review any calling integration for assumptions about response type, serialization, or error handling.
-
Update the RESTlet or integration as needed, then retest the complete request flow.
For more information, see SuiteScript 2.1 RESTlet Script Type.