You have a few dozen scripts annotated @NApiVersion 2.x. Oracle has made SuiteScript 2.1 the standard, and someone on the team has found a setting under Setup > Company > Preferences > General Preferences that promises to run all of them as 2.1 without touching a file. The question is simple: if you flip it, does everything keep working?
Mostly yes, but not everywhere, and the failures are not all loud. This guide covers what the preference really does, the documented differences that bite, and how to test the switch in a sandbox before production finds the problems for you.
The Short Answer
In one paragraph
Setting Execute SuiteScript 2.x Server Scripts As to 2.1 runs every @NApiVersion 2.x server script on the 2.1 engine. Scripts written in clean ECMAScript 5.1 usually keep working. Scripts that rely on old Rhino-era leniency (for each...in, conditional catch, undeclared variables, trailing commas in JSON) fail. RESTlets and anything that serializes errors or formats dates can change output without failing. Client scripts are not affected, upload validation still uses 2.0 rules, and the switch is account-wide, so test it in a sandbox first.
Why This Matters Now
This is no longer optional housekeeping. Oracle's transition guidance sets a dated path away from 2.0 and 2.x annotations:
| Release | What Oracle says changes |
|---|---|
| 2026.2 | SuiteScript 2.1 becomes the standard scripting model for new and existing scripts. |
| 2027.1 | SuiteScript 1.0 enters end-of-life support (critical issues only). |
| 2028.1 | SuiteScript 2.0/2.x scripts run as SuiteScript 2.1 by default. 1.0 can no longer be deployed in new accounts. |
| 2028.2 | All new and existing scripts must use SuiteScript 2.1. |
Read the 2028.1 row again. Whether or not you touch the preference, your 2.x scripts are scheduled to run on the 2.1 engine by default. The preference lets you find out what breaks on your timetable instead of during an upgrade window.
Two Preferences, Not One
General Preferences has two separate settings, and they behave differently. Most confusion comes from treating them as the same switch.
Field type
- Execute SuiteScript 2.x Server Scripts As
- Dropdown — select 2.1
- Execute SuiteScript 2.0 Server Scripts As 2.1
- Checkbox
Applies to
- Execute SuiteScript 2.x Server Scripts As
- Server scripts annotated @NApiVersion 2.x
- Execute SuiteScript 2.0 Server Scripts As 2.1
- Server scripts annotated @NApiVersion 2.0
Scope
- Execute SuiteScript 2.x Server Scripts As
- All matching scripts in the account at once
- Execute SuiteScript 2.0 Server Scripts As 2.1
- Only 2.0 scripts NetSuite recognises as compatible with 2.1
If a script is not compatible
- Execute SuiteScript 2.x Server Scripts As
- It runs on 2.1 and fails or behaves differently
- Execute SuiteScript 2.0 Server Scripts As 2.1
- It quietly keeps running as 2.0
Who can set it
- Execute SuiteScript 2.x Server Scripts As
- Administrator
- Execute SuiteScript 2.0 Server Scripts As 2.1
- Administrator
The 2.0 checkbox is the more forgiving of the two because it skips scripts NetSuite does not consider compatible. That is also its trap: a script can look as if it “passed” when it never ran on 2.1 at all. Always confirm the runtime on the script record's Execute As Version field instead of assuming.
What the Preference Does Not Do
- It does not let you write 2.1 code in a 2.x file. Upload validation still follows the file's annotation. Oracle states that a script annotated 2.x or 2.0 that contains 2.1-only syntax (arrow functions, let, template literals, async) returns a syntax error on upload, even with the preference set to 2.1.
- It does not touch client scripts. Oracle's troubleshooting guide is explicit that client scripts are not affected by the server-script preference. Their annotation has to be changed and tested separately.
- It does not override a script record set to run as 2.0. A script record whose Execute As field is 2.0 keeps running as 2.0.
- It does not cover script types that 2.1 does not support. Those are left alone.
- It does not change your files. When you are done testing, the scripts still say 2.x. The end state Oracle wants is the annotation changed to 2.1.
The upload check is not a 2.1 compatibility check
Because uploads are validated under 2.0 rules, a 2.x file containing for each...in or a conditional catch uploads cleanly today. With the preference on, the first sign of trouble is a SyntaxError when the script loads at run time — often in a scheduled or Map/Reduce script nobody is watching.
What Breaks Under the 2.1 Runtime
SuiteScript 2.1 runs on a different engine and targets ECMAScript 2023, where 2.0 targets ECMAScript 5.1. Oracle documents the differences below. I group them by how you find out: some fail loudly, others change output and keep running.
Pattern
for each (var v in obj)
- SuiteScript 2.0
- Runs
- SuiteScript 2.1
- SyntaxError: Expected ( but found each
- How you find out
- Script fails to load
Pattern
catch (e if e instanceof TypeError)
- SuiteScript 2.0
- Runs
- SuiteScript 2.1
- SyntaxError: Expected ) but found if
- How you find out
- Script fails to load
Pattern
extends (or another newer reserved word) as a name
- SuiteScript 2.0
- Runs
- SuiteScript 2.1
- Syntax error
- How you find out
- Script fails to load
Pattern
Assigning an undeclared variable
- SuiteScript 2.0
- Runs
- SuiteScript 2.1
- ReferenceError: x is not defined
- How you find out
- Fails at that line
Pattern
Reassigning a const
- SuiteScript 2.0
- Runs; value silently unchanged
- SuiteScript 2.1
- TypeError: Assignment to constant variable
- How you find out
- Fails at that line
Pattern
JSON.parse with a trailing comma
- SuiteScript 2.0
- Parses
- SuiteScript 2.1
- SyntaxError: Invalid JSON …
- How you find out
- Fails at that line
Pattern
RESTlet returning JSON.stringify(x) with Content-Type application/json
- SuiteScript 2.0
- Caller receives a string
- SuiteScript 2.1
- Caller receives an object
- How you find out
- Integration behaves differently
Pattern
RESTlet post() return value
- SuiteScript 2.0
- Extra JSON.stringify added internally
- SuiteScript 2.1
- No extra stringify
- How you find out
- Callers see different escaping and length
Pattern
JSON.stringify(new Error('msg'))
- SuiteScript 2.0
- Includes message
- SuiteScript 2.1
- {} — message dropped
- How you find out
- Logs or responses lose detail
Pattern
Date toLocaleDateString() default
- SuiteScript 2.0
- Long format
- SuiteScript 2.1
- Short format
- How you find out
- Text output changes
Pattern
setValue with 616.00
- SuiteScript 2.0
- Stored as double 616.0
- SuiteScript 2.1
- Stored as integer 616
- How you find out
- Value type changes
Pattern
parseInt('08')
- SuiteScript 2.0
- Oracle documents no value
- SuiteScript 2.1
- 8
- How you find out
- Calculation differs
The first group is the least dangerous: the script fails, the execution log shows the error, and you fix it. The last group is where the real risk sits. A RESTlet that changes response type does not throw in NetSuite; the middleware on the other end breaks, or worse, keeps going with a different shape of data.
RESTlets deserve their own test pass
If you flip the 2.x preference in an account with integration RESTlets, every 2.x RESTlet changes runtime at the same moment. Retest each HTTP method against the real calling system and compare request and response bodies with the 2.0 results before you go anywhere near production.
Fixing the Code Without Leaving 2.x
The useful goal for most teams is code that behaves the same on both engines. Then the preference is safe to switch on and off while you test, and you can change the annotation to 2.1 later without a second round of fixes. Here is a scheduled script with most of the classic problems in one place:
/**
* @NApiVersion 2.x
* @NScriptType ScheduledScript
*/
define(['N/search', 'N/log'], function (search, log) {
function execute() {
var config = JSON.parse('{"batchSize": 50, }'); // 2.1: SyntaxError (trailing comma)
total = 0; // 2.1: ReferenceError (undeclared)
const LIMIT = 100;
LIMIT = 200; // 2.1: TypeError (const reassignment)
try {
// search.load() costs 5 units; run().each() costs 10 units per call
search.load({ id: 'customsearch_open_orders' }).run().each(function (r) {
for each (var v in r.getAllValues()) { total += 1; } // 2.1: SyntaxError
return true;
});
} catch (e if e.name === 'SSS_USAGE_LIMIT_EXCEEDED') { // 2.1: SyntaxError
log.error('governance', e.message);
}
var day = parseInt('08'); // 2.0 and 2.1 return different values
}
return { execute: execute };
});The fixed version stays inside ECMAScript 5.1 syntax, so it still uploads under the 2.x annotation and runs identically on both engines:
/**
* @NApiVersion 2.x
* @NScriptType ScheduledScript
*/
// Still ES5.1 syntax, so it uploads under 2.x AND runs the same under the 2.1 runtime.
define(['N/search', 'N/log'], function (search, log) {
function execute() {
var config = JSON.parse('{"batchSize": 50}'); // valid JSON in both runtimes
var total = 0; // declared
var LIMIT = 100; // var if you genuinely reassign it
LIMIT = 200;
try {
// Governance unchanged by the fix: load (5) + each (10) = 15 units
search.load({ id: 'customsearch_open_orders' }).run().each(function (r) {
var values = r.getAllValues();
for (var key in values) { // standard for...in
if (values.hasOwnProperty(key)) total += 1;
}
return true;
});
} catch (e) {
if (e.name === 'SSS_USAGE_LIMIT_EXCEEDED') { // condition moved inside catch
log.error('governance', e.message);
} else {
throw e;
}
}
var day = parseInt('08', 10); // always pass the radix
}
return { execute: execute };
});Two of those fixes are worth making a team standard regardless of version: always pass a radix to parseInt, and never use a conditional catch. For errors that end up serialized (RESTlet responses, logged JSON), Oracle's own advice is to create the Error with no argument and assign message afterwards, because only then is message an enumerable property that 2.1 includes in JSON.stringify.
Scan Before You Switch
Before you change anything in an account, pull the scripts down (an SDF project or a File Cabinet export) and scan them. The script below reports every file's @NApiVersion and flags the documented patterns line by line. It is a regex scan, so treat it as a list of places to read, not as proof of safety.
// scan-ss21-risk.js — run locally with Node 18+: node scan-ss21-risk.js ./src/FileCabinet
// Reads every .js file, reports its @NApiVersion, and flags patterns that
// Oracle documents as behaving differently (or failing) in SuiteScript 2.1.
// Runs on your machine, not in NetSuite, so it consumes no governance.
const fs = require('fs');
const path = require('path');
const CHECKS = [
{ id: 'for-each-in', level: 'FAIL', re: /\bfor\s+each\s*\(/, note: 'SyntaxError in 2.1 - use for...in or for...of' },
{ id: 'conditional-catch', level: 'FAIL', re: /catch\s*\(\s*\w+\s+if\b/, note: 'SyntaxError in 2.1 - move the condition inside catch' },
{ id: 'reserved-word', level: 'FAIL', re: /\b(?:var|let|const|function)\s+(?:extends|class|super|enum|import|export|static|yield|await|implements|interface|package|private|protected|public)\b/, note: 'Reserved word used as an identifier' },
{ id: 'to-source', level: 'FAIL', re: /\.toSource\s*\(/, note: 'toSource() is listed as a 2.1 difference' },
{ id: 'json-trailing-comma', level: 'FAIL', re: /,\s*[}\]]\s*['"]/, note: 'Possible trailing comma inside a JSON string - JSON.parse throws in 2.1' },
{ id: 'parseint-no-radix', level: 'CHANGE', re: /\bparseInt\s*\(\s*[^,()]+\)/, note: 'parseInt without radix - pass 10 explicitly' },
{ id: 'locale-date', level: 'CHANGE', re: /\.toLocaleDateString\s*\(/, note: 'Default date string format changes from long to short' },
{ id: 'error-with-arg', level: 'CHANGE', re: /new\s+Error\s*\(\s*[^)\s]/, note: 'If this error is JSON.stringify-ed, message is dropped in 2.1' },
{ id: 'restlet-stringify', level: 'CHANGE', re: /return\s+JSON\.stringify\s*\(/, restletOnly: true, note: 'RESTlet response type/escaping changes in 2.1 - retest callers' },
];
function walk(dir, out) {
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) walk(full, out);
else if (entry.name.endsWith('.js')) out.push(full);
}
return out;
}
function tagValue(source, tag) {
const match = source.match(new RegExp('@' + tag + '\\s+([\\w.]+)', 'i'));
return match ? match[1].toLowerCase() : 'none';
}
const root = process.argv[2] || '.';
const summary = { '2.0': 0, '2.x': 0, '2.1': 0, other: 0 };
for (const file of walk(root, [])) {
const source = fs.readFileSync(file, 'utf8');
const version = tagValue(source, 'NApiVersion');
const scriptType = tagValue(source, 'NScriptType');
summary[version in summary ? version : 'other'] += 1;
if (version === '2.1' || version === 'none') continue; // already 2.1, or a library/1.0 file
const lines = source.split(/\r?\n/);
lines.forEach(function (line, i) {
for (const check of CHECKS) {
if (check.restletOnly && scriptType !== 'restlet') continue;
if (check.re.test(line)) {
console.log([check.level, version, scriptType, file + ':' + (i + 1), check.id, check.note].join(' | '));
}
}
});
}
console.log('\nFiles by @NApiVersion:', JSON.stringify(summary));FAIL lines are patterns Oracle documents as errors under 2.1. CHANGE lines are patterns where 2.1 gives a different result; read each one and decide whether the difference matters to the caller. The scan cannot reliably catch undeclared variables or const reassignment; use ESLint's no-undef and no-const-assign rules for those (see Alternative Approaches).
A Sandbox Test Plan
- Inventory. Run the scanner and list every 2.x and 2.0 server script, its type, and its deployments. Mark scripts that are inactive or obsolete for retirement instead of testing.
- Fix the FAIL lines in source control and deploy the fixes to the sandbox while the preference is still off. ES5.1-safe fixes run the same on 2.0, so this step should change nothing.
- Set Execute SuiteScript 2.x Server Scripts As to 2.1 in the sandbox (and tick the 2.0 checkbox if you also have 2.0 scripts).
- Confirm the runtime on a sample of script records using the Execute As Version field. Any 2.0 script still showing 2.0 was judged incompatible, or its record is pinned to 2.0.
- Exercise every entry point. Save records to fire user events, run scheduled and Map/Reduce deployments on demand, and call each RESTlet method from the real integration or a recorded request.
- Compare outputs, not just errors. Check RESTlet responses, generated files, emails, date text, and any numeric fields set from code against a 2.0 baseline.
- Read the execution logs for SyntaxError, ReferenceError, and TypeError entries across all script deployments, not just the ones you tested by hand.
- Change annotations to 2.1 for scripts that pass, in small groups, and redeploy. Only then switch the preference on in production, or skip that and rely on the annotations.
Rolling back
You can set either preference back to 2.0 at any time, and Oracle notes that scripts explicitly annotated @NApiVersion 2.1 keep running as 2.1 when you do. The preference is a safe way to test because the files are unchanged — but only until you start writing 2.1 syntax into 2.x files, which the 2.0 upload rules will reject.
Governance and Performance
- The preference itself costs nothing. It is an account setting, not a script, and the scanner above runs on your machine.
- Governance is not on Oracle's list of 2.0/2.1 differences. Usage is charged per API call and limited per script type, and the fixes above do not change which N/ module calls a script makes — the example uses the same 15 units before and after. Still compare remaining usage in the logs for your heaviest scripts during testing rather than assuming.
- Oracle describes the 2.1 runtime as faster and more stable than the 2.0 engine. Treat that as a reason to migrate, not as a number to plan capacity around; measure execution time for long-running scheduled and Map/Reduce scripts before and after.
- Async only helps where it is supported. Once a script is annotated 2.1, server-side async/await and promises are supported only in N/http, N/https, N/llm, N/query, N/search, and N/transaction. Using them with other modules raises an error.
- Some modules require 2.1. N/llm and N/pgp (and N/crypto/random in server scripts) are only supported in 2.1, so the preference does not give a 2.x script access to them; the annotation must change.
Alternative Approaches
Change annotations one script at a time. Edit @NApiVersion 2.1 into a single file, upload, and test it. Only that script changes runtime, nothing else in the account moves, and you can start using 2.1 syntax in it immediately. This is slower but it is the better choice in production accounts with critical RESTlets, because the account-wide switch moves every 2.x RESTlet at once.
Lint instead of (or as well as) regex. Running ESLint over the repository with no-undef, no-const-assign, and radix enabled catches the strict-mode and parseInt issues more reliably than a line scan. It needs the SuiteScript globals (define, log) declared so it does not flag them.
Wait for 2028.1. Oracle's timeline runs 2.x scripts as 2.1 by default from 2028.1. Waiting means doing the same testing later, inside an upgrade window, with less control over timing. I would not recommend it for accounts with integration RESTlets.
Common Mistakes
- Flipping the 2.x preference in production first. It is account-wide. Test it in a sandbox or Release Preview account.
- Treating a successful upload as proof of compatibility. Uploads are validated against 2.0 rules for 2.x files.
- Assuming the 2.0 checkbox ran a script on 2.1. Incompatible 2.0 scripts stay on 2.0 silently; check Execute As Version.
- Adding arrow functions or let to a 2.x file because "the account runs 2.1 now." The upload fails. Change the annotation first.
- Forgetting client scripts. They are outside the preference and still need their own migration.
- Testing only for errors. RESTlet response shape, serialized errors, and date strings change without throwing.
- Leaving the preference as the end state. The 2028.2 requirement is about scripts using 2.1, so the annotations still need to change.
Decision
If most of your custom code is ordinary 2.x scheduled, user event, and Map/Reduce scripts, scan it, fix the FAIL lines, and turn the 2.x preference on in a sandbox this quarter. It is the cheapest way to find out how far you are from 2.1. If your account depends on RESTlets for integrations, change those annotations one by one with a full integration retest each time, and keep the account-wide switch for the remaining scripts.
If a migrated batch job starts running out of time or usage, the Scheduled Script vs Map/Reduce decision guide covers when to restructure instead of patching.
For runtime failures that only surface as a generic error after the switch, start with the NetSuite error resolution hub.
2.1 is the standard from 2026.2 onward; see what else changed in NetSuite 2026.2 before you scope new scripts.
Sources
Behaviour claims in this article are taken from Oracle's NetSuite Help Center, checked on November 3, 2026. Help Center wording changes between releases; recheck before relying on a specific detail.
Enabling SuiteScript 2.1 at the Account Level
Setting General SuiteScript and Advanced Preferences
Transitioning to SuiteScript 2.1
Troubleshooting SuiteScript 2.1 Migration Issues
Frequently Asked Questions
- If I set Execute SuiteScript 2.x Server Scripts As to 2.1, will my 2.x scripts still work?
- Scripts written in standard ECMAScript 5.1 usually do. Scripts that use for each...in, conditional catch blocks, undeclared variables, const reassignment, or trailing commas in JSON fail under 2.1, and RESTlets, serialized errors, date strings, and parseInt can return different results. Test in a sandbox first.
- Can I use arrow functions or let in a 2.x script once the preference is set to 2.1?
- No. Oracle states that scripts annotated 2.x or 2.0 are still validated with SuiteScript 2.0 syntax rules on upload, so 2.1-only syntax returns a syntax error. Change the annotation to @NApiVersion 2.1 to use 2.1 syntax.
- Does the preference affect client scripts?
- No. Oracle's troubleshooting guidance says client scripts are not affected by the server-script preference. Change and test their annotations separately.
- How do I know which version a script actually ran as?
- Open the script record and check the Execute As Version field. With the 2.0 checkbox in particular, scripts NetSuite does not recognise as compatible keep running as 2.0.
- Can I undo the change?
- Yes. Either preference can be set back to 2.0 at any time. Scripts explicitly annotated @NApiVersion 2.1 keep running as 2.1.
- Do I have to migrate if the preference works?
- Yes. Oracle's timeline runs 2.0/2.x scripts as 2.1 by default from 2028.1 and requires all scripts to use SuiteScript 2.1 by 2028.2. The preference is a testing tool; the end state is the annotation set to 2.1.