Fix: UNEXPECTED_ERROR — NetSuite Generic Error Guide

UNEXPECTED_ERROR: An unexpected error has occurred.

Why This Happens

• A SuiteScript runtime error that NetSuite doesn't map to a specific error code
• Database deadlock — two operations trying to modify the same record simultaneously
• NetSuite platform issue — transient errors during deployments or maintenance windows
• Memory limit exceeded — script allocated too much data (e.g., loading 100K search results into an array)
• An unhandled error in a Workflow action script or formula
• Corrupt record data — rare, but possible after failed upgrades or data imports

How to Fix It

1. Step 1: Check the Execution Log for surrounding context

   Go to Customization > Scripting > Script Execution Log. Filter by your script and the time of the error. Look at log entries just before the UNEXPECTED_ERROR. The last successful log.debug message tells you where the code got to before failing.

2. Step 2: Wrap the entire entry point in try/catch

   Add a broad try/catch around your script's entry point function with detailed error logging. Capture e.name, e.message, e.stack, e.cause, and the full JSON.stringify of the error object. This often reveals sub-errors that UNEXPECTED_ERROR hides.

3. Step 3: Check for concurrent modification

   If the error occurs during record.save(), it might be a deadlock. Two scripts, workflows, or users trying to save the same record at the same time can cause this. Check if the error is intermittent and correlates with high-activity periods.

4. Step 4: Isolate by commenting out code sections

   If you can't find the cause, use binary search debugging: comment out half the code, test, and see if the error persists. Narrow down to the exact line. This is tedious but reliable for truly opaque UNEXPECTED_ERROR cases.

Code Example

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 *
 * Pattern: comprehensive error handler for UNEXPECTED_ERROR debugging.
 * Captures all error properties and logs them for diagnosis.
 */
define(['N/log', 'N/runtime'], (log, runtime) => {

  function afterSubmit(context) {
    try {
      // Your actual business logic here
      processRecord(context);
    } catch (e) {
      // Capture EVERYTHING — UNEXPECTED_ERROR hides useful details
      const errorDetails = {
        name: e.name || 'Unknown',
        message: e.message || 'No message',
        type: e.type || 'Unknown type',
        stack: e.stack || 'No stack trace',
        cause: e.cause ? JSON.stringify(e.cause) : 'No cause',
        id: e.id || 'No error ID',
        // SuiteScript-specific error properties
        userFacing: e.userFacing || false,
        notifyOff: e.notifyOff || false,
        // Context at time of error
        recordType: context.newRecord.type,
        recordId: context.newRecord.id,
        executionContext: runtime.executionContext,
        remainingUsage: runtime.getCurrentScript().getRemainingUsage()
      };

      log.error('UNEXPECTED_ERROR details', JSON.stringify(errorDetails, null, 2));

      // Try serialising the entire error object
      try {
        log.error('Full error object', JSON.stringify(e, Object.getOwnPropertyNames(e)));
      } catch (serErr) {
        log.error('Could not serialise error', serErr.message);
      }

      throw e; // Re-throw so NetSuite records the failure
    }
  }

  function processRecord(context) {
    // Replace with your actual logic
  }

  return { afterSubmit };
});

Common Mistakes

• Ignoring the error because it's 'transient' — some UNEXPECTED_ERRORs are genuine bugs hidden behind a bad error message
• Not logging the full error object — e.message alone often says 'An unexpected error has occurred' with no additional context
• Blaming the NetSuite platform without checking your own code first — 90% of UNEXPECTED_ERROR cases are caused by application code, not platform bugs
• Not checking the Script Execution Log — the logs from just before the error usually point to the exact cause

Alternative Approaches

• If the error is intermittent and correlates with high load, implement retry logic with exponential backoff
• For persistent UNEXPECTED_ERROR on a specific record, try loading the record in the UI and saving it manually — if it fails, the record data may be corrupt and NetSuite Support can help
• Use the N/error module's create() method to throw custom errors — when your code fails, you'll see YOUR error instead of UNEXPECTED_ERROR

Related Errors