NetSuite Sync Troubleshooting Tips

This guide explains common NetSuite sync failures, how to diagnose them, and best practices for working with NetSuite fields, especially sublist (line-level) fields on transaction records.

Using NetSuite API Documentation

To confirm valid fields and structure:

1. Open the NetSuite Schema Browser

2. Search for the record type (for example, Journal Entry)

3. Review:

   • Header/body fields

   • Sublist fields (such as lineList, itemList, or applyList)

4. Click into the sublist definition to see:

   • Available fields

   • Required vs optional fields

This is the most reliable way to validate field names and structure.

Sublist Field Formatting

What Is a Sublist?

Many NetSuite records contain sublists:

• Header (body) fields High-level information such as date, currency, or memo

• Sublist (line) fields Line-item details such as account, item, amount, or quantity

Example: Journal Entry

• Header: Post date, currency, memo

• Sublist: Debit and credit lines, account, amount

---

Sublist Field Structure

Sublist fields are sent as arrays of objects in the NetSuite API.

Example:

[
  { "account": { "internalId": 426 }, "credit": 13 },
  { "account": { "internalId": 426 }, "debit": 13 }
]

Important notes:

• Sublist fields are the most common source of NetSuite sync errors

• Field names are case-sensitive

• Fields must match NetSuite’s API schema exactly

---

Apply Fields (Special Sublist Case)

Some transactions can be applied to other transactions, such as:

• Applying a vendor credit to a bill

• Applying a payment to an invoice

These fields behave like sublists and often include:

• apply

• amount

• doc

• line

Example:

[
  { "apply": true, "doc": "9247", "total": 12 }
]

Key detail: doc should be the internal ID of the transaction being applied.

Common NetSuite Sync Error

Error Message: Passed nil into T.must

What This Means

This error often indicates that a field included in your sync configuration could not be found or resolved by NetSuite.

In many cases, the issue is related to a sublist (line-level) field.

• A sublist field does not exist on the record type being synced

• The field name is not an exact match (NetSuite is case-sensitive)

• A custom field is referenced using its label instead of its ScriptID

• A recently added field is not yet available via the NetSuite API

---

How to Troubleshoot

1. Review the Fields in Your Sync Configuration

• Identify which fields are being written to NetSuite, especially line-level (sublist) fields

• Double-check spelling and capitalization

2. Confirm the Field Exists on the Correct Sublist

Fields must exist on the exact sublist being used (for example, itemList, lineList, or applyList).

A field that exists on one transaction type or sublist may not exist on another.

---

3. Validate Custom Fields

If the field is custom:

• Confirm it was created as a Transaction Line Field (not a body field)

• Ensure you are using the Script ID, not the display label

To find the Script ID in NetSuite:

1. Go to Customization → Lists, Records, & Fields → Transaction Line Fields

2. Open the field

3. Use the value shown as ID (for example: custcol_example_field)

---

Alternative Approach: HTTP Request Object

For complex scenarios or unsupported objects, you can use the HTTP Request object to interact directly with NetSuite’s REST API.

Benefits

• Easier debugging

• More flexible field handling

NetSuite’s REST API documentation often provides clearer examples that can be tested iteratively.