Expand your SuiteScript skills in the Sustainable SuiteScript community for NetSuite developers.

Foundational SuiteScript Troubleshooting Techniques

Created: July 22, 2024

During a recent Sustainable SuiteScript AMA, I was asked what mistakes I consistently see SuiteScript beginners make. The original recording is available on my YouTube channel. In this miniseries, I expand on the answer I gave in the live session.

The question used the word "mistakes". I want to re-frame that and talk about three important lessons I believe all new NetSuite developers should learn:

Learn Foundational Troubleshooting Techniques

The second lesson for NetSuite developers is to learn the basics of troubleshooting software problems.

Too often, I see new developers panic at the first sign of trouble and reach out for help.

Let me be clear - I am not shaming anyone for asking for help. Spinning our wheels for days on a problem doesn't teach us anything; it only breeds frustration. It is important to recognize when you're stuck and need another pair of eyes - as we'll see in the next lesson.

But, just because a little red ERROR message looks vaguely threatening doesn't mean we need to cower in fear. Knowing how to read those messages is a foundational skill for any software developer.

How to Read SuiteScript Error Messages

Errors in JavaScript are Objects like any other. These objects contain properties that assist in troubleshooting the cause of the error. We can inspect the properties in the browser console or execution logs as we would with other data Objects.

Here is an example of an error thrown by the record.load function in the browser console.

An example of an error object thrown by record.load

The most important properties of an Error are typically:

  • stack - The stack shows us the chain of function calls that were made prior to the Error. More on the stack trace in a moment.
  • name - An identifier for the type of Error, e.g. SSS_MISSING_REQD_ARGUMENT. Often you can search for the name in NetSuite Help to find more details on what this type of Error represents.
  • message - A longer text description of the Error. In the example, the message is informing us that the load function was called, but its type argument was missing.

Understanding that Errors are no different from standard Objects should help to demystify them. You can inspect and explore them with the same tools and procedures you would with any other Object.

How to Read a Stack Trace

In JavaScript, and by extension SuiteScript, errors contain a "stack trace". In general programming terms, the "call stack" (or just "stack") is the list of function calls which have been made up to the current point in execution. A "trace" is a detailed log or recording of events.

An error's "stack trace" is then the detailed log of the function calls which had been made up until the time of the error. With each function in the list, you can see the name of the function, the file it was called from, and the line number where the call was made.

An example of a stacktrace from the previous error

In this example stack trace, at index 12, we see the following string:

"loadRecord@https://tstdrv1555136.app.netsuite.com/javascript/suitescript/2.0/client/N.js?NS_VER=2024.1&minver=15&buildver=31044:73047:52"

The string is in the format:

functionName@fileName:lineNumber:columnNumber

Note that the format will not be exactly the same in all browsers or engines, but the same information will be present.

This entry in the stack trace tells us that along the way to our error, the loadRecord function was called in NetSuite's N.js file on line 73047.

It is called a "stack" trace because the function calls are "stacked" on top of each other as they happen. The most recent function call that occurred is the first (index 0) on the stack, similar to stacking dinner plates. As you proceed "down" the stack, you progress backward in time through earlier function calls.

Once you understand how to read the stack trace, it can help you narrow down precisely where the error is surfacing and what path your code took to get there. This is a vital skill for NetSuite developers.

DigitalOcean has a good writeup on understanding JavaScript's stack trace: Don't Be Afraid of the JavaScript Stack Trace

Study Common Errors

If you write code for any amount of time, you'll inevitably run into a small range of similar errors. It's worth studying and internalizing what these most common errors mean and how to fix them.

For general JavaScript errors, the Mozilla Developer Network has a massive reference list.

Some important, frequent errors worth studying are:

Similarly, NetSuite provides a large reference list of errors, and there are a few SuiteScript-specific errors that are worth remembering:

  • SSS_USAGE_LIMIT_EXCEEDED: Your script has exceeded its governance usage limit; you'll need to assess and optimize the script's usage. I made a video explaining NetSuite's governance system if you are not yet familiar.
  • "entry point scripts must implement one script type function": This indicates that your script does not correctly export any entry point handlers. Validate and correct your script module's return statement.
  • Entry Point Validation Errors: You'll see these when you attempt to upload or update a script file, rather than when a script executes.

Logging is Your Best Friend

One of the most common troubleshooting tools for developers is Logging. Logs are plain-text messages that we can define in our code to inform us about our code's behavior as it runs.

You can use log messages:

  • to inform you when a function gets called or exits
  • as sign posts denoting locations in your code, so you know which parts ran and which parts failed
  • to print out the data contained in variables to validate behavior
  • to refine or augment error messages with more detail

and much, much more.

I cannot understate the importance of writing informative logging.

NetSuite provides the N/log module for creating log messages, and it accumulates our messages in the Script Execution Log.

I have written an article and made a video detailing my approach to logging in SuiteScript.

Go Forth and Study

To send you on your way, here are a few more great introductory resources for learning troubleshooting techniques and tools: