NetSuite troubleshooting

Connection errors

Data center error

• Symptom: A NetSuite connection that previously tested successfully now fails with this error:

  Connector Error: Error getting the data center URL.

  Caused by: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

  In this account, you must use account-specific domains with this SOAP web services endpoint. You can use the SOAP getDataCenterUrls operation to obtain the correct domain. Or, go to Setup > Company > Company Information in the NetSuite UI. Your domains are listed on the Company URLs tab.

  In some circumstances, this error may appear instead:

  You are not requesting the correct data center for your company.

• Cause: Due to changes made by NetSuite, some WSDL URL formats that were previously allowed are no longer accepted, including generic and data center-specific WSDL URLs. For example:

  • Generic WSDL URL: https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
  • Data center-specific WSDL URL: https://webservices.na3.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl

• Workaround: Change the WSDL URL to use an account-specific domain:

  • Account-specific WSDL URL: https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl

  For instructions on finding the NetSuite account-specific domain and using it in the WSDL URL, see Use a NetSuite account-specific WSDL URL.

Insufficient permissions

• Symptom: Even if testing a NetSuite connection is successful, you may receive an INSUFFICIENT_PERMISSION error when running operations containing activities using that connection.
• Workaround: When generating access tokens, use either a Full Access or Administrator role, or ensure the appropriate permissions are allowed for the role being used. Detailed instructions are available in NetSuite's documentation Getting Started with Token-based Authentication.

Sandbox connection fails after sandbox refresh

• Symptom: A NetSuite connection configured for a NetSuite sandbox account fails with an authentication error after the sandbox environment has been refreshed.
• Cause: Each time a NetSuite sandbox is refreshed, all token-based authentication (TBA) tokens associated with that sandbox are invalidated. The connection continues to use the old tokens, which are no longer accepted by NetSuite.
• Resolution: After each sandbox refresh, generate new TBA tokens for the sandbox account and update the Token key and Token secret fields in the NetSuite connection. For instructions on obtaining new token values, see Gather values for using NetSuite TBA.

Schema and field issues

Custom fields not appearing in the activity schema

• Symptom: Custom fields for a NetSuite object are not present in the transformation schema on a private agent, even though those fields exist in NetSuite.
• Cause: The NetSuite connector exposes custom fields for many objects by default, but some objects require explicit configuration in the agent's NetSuite connector configuration file.
• Resolution: Add the object to the netsuiteconfig.xml configuration file on the private agent. See Expose custom fields in the NetSuite connector for full instructions, including how to handle objects with more than 1,000 custom fields.

Custom segments not appearing or not supported in advanced searches

• Symptom: Custom segments are not visible in the activity schema, or custom segments of the List/Record type are unavailable in an advanced search.
• Cause: Custom segments require specific permissions on the NetSuite user account. Additionally, the List/Record segment type is not supported in advanced searches — only the Multiple Select type is.
• Resolution: See Custom segments on the NetSuite Search activity page for permission requirements and known limitations.

Custom body fields not visible due to missing role permission

• Symptom: Custom transaction body fields (for example, fields added to a Sales Order or other transaction record) do not appear in the NetSuite Search activity output schema, even though the fields exist in the NetSuite instance and the connection test succeeds.
• Possible cause: The NetSuite role used by the integration does not have View permission for Custom Body Fields. The NetSuite connector calls the getList SOAP action to retrieve custom field definitions; a permission violation on that call causes the fields to be omitted from the schema entirely.
• Resolution:
  1. In your NetSuite account, open the role assigned to the integration user and grant at least View access to the Custom Body Fields permission.
  2. Save the role and allow a few minutes for the permission change to take effect.
  3. In Studio, create a new NetSuite Search activity or import the project into a new project environment to clear the cached schema. The custom body fields should now appear in the output schema.

Activity configuration errors

Saved searches not appearing in the dropdown

• Symptom: When configuring a NetSuite Search activity using a Saved Search search type, the Select a Saved Search dropdown appears empty or does not list all expected saved searches.
• Cause: The NetSuite API limits responses to 1,000 records per request. When an object has more than 1,000 saved searches, the dropdown cannot list all of them and may appear empty.
• Resolution: Use the Provide Saved Search Script ID option to bypass the dropdown:
  1. In the Select a Saved Search section of the activity configuration, select Provide Saved Search Script ID.
  2. Enter the script ID of the target saved search directly. The script ID can be found in the NetSuite UI on the saved search's detail page.

Expanded search: Test Query button is disabled

• Symptom: When configuring an expanded search in the NetSuite Search activity, the Test Query button is grayed out and cannot be clicked.
• Cause: An expanded search requires a query condition on a related object. The Test Query button is disabled when no condition on a related object has been added.
• Resolution: Add at least one condition that filters on a related object. If the search requires filtering only on the current object's own fields, use a Basic search type instead of an expanded search.

Saved search formula fields are missing from the activity output

• Symptom: A NetSuite Search activity that uses a saved search returns the expected record count in Test Query, but formula-based or complex-join columns (for example, customSearchJoin fields) are missing from the activity output and the transformation mapping, even though those columns appear in the saved search in the NetSuite UI.
• Cause: Formula-based saved-search columns are computed at the NetSuite UI level and are not included in the SOAP response that the connector reads. As a result, those values do not surface in the activity output even though the search returns records.
• Resolution:
  1. Where possible, rebuild the saved search using stored (non-formula) fields, since formula-computed values may not be returned through the API.
  2. In Studio, open the NetSuite Search activity and, on the first configuration page, select the Saved Search (use reusable search definition previously saved in NetSuite) option.
  3. Select the saved search from the Select a Saved Search dropdown.
  4. Step through the remaining pages and run the operation to retrieve the full data.

Test Query returns parse error when filter uses a project variable

• Symptom: When a NetSuite Search activity filter uses a project variable for a date or datetime value (such as lastModifiedDate), clicking Test Query in the activity configuration returns a 500 error referencing an invalid date format. The same operation runs successfully at runtime.

  Connector Error: FaultString: java.text.ParseException: Invalid dateTime format: [lastModifiedDate]
  

• Cause: Test Query does not resolve project variables. It sends the literal variable reference (for example, [lastModifiedDate]) as the filter value, which NetSuite rejects as an invalid date. At runtime, the agent substitutes the variable's actual value, so the operation itself succeeds.

• Resolution: To test or save changes to the activity without removing the variable, add a temporary default value to the variable reference in the filter condition:
  1. In the filter, change the variable reference from [my_date_variable] to [my_date_variable{2023-01-01T00:00:00.000Z}] (using the appropriate ISO 8601 datetime as the default).
  2. Click Test Query. The test now succeeds because a valid date is substituted in place of the unresolved variable.
  3. Save any other changes to the activity. The default value can be left in place; at runtime the agent always uses the current value of the project variable.

Saved Search with result fields as output requires agent 11.49 or later

• Symptom: In the NetSuite Search activity, the Saved search with result fields as output option is visible in the activity UI but operations using it fail with a 500 error when run on an older private agent.
• Cause: The Saved search with result fields as output feature was introduced in agent version 11.49. Private agents on earlier versions render the option in the UI but do not have the runtime support to execute it.
• Resolution:
  1. Confirm the agent version on the Agents page in the Management Console.
  2. Upgrade private agents to version 11.49 or later to use this option. Cloud agents are kept current automatically.
  3. If upgrading the private agent is not possible, reconfigure the activity to use Saved Search instead. This mode is supported on earlier agent versions.

Update activity returns INVALID_KEY_OR_REF when source XML loses internalId

• Symptom: A NetSuite Update activity completes without raising an exception, but no record is updated in NetSuite. The response payload contains the INVALID_KEY_OR_REF SOAP status. The issue commonly appears when a transformation script uses GetXMLString to build the update payload from a prior search response.

  <writeResponse>
    <platformCore:status isSuccess="false">
      <platformCore:statusDetail type="ERROR">
        <platformCore:code>INVALID_KEY_OR_REF</platformCore:code>
        <platformCore:message>The specified key is invalid.</platformCore:message>
      </platformCore:statusDetail>
    </platformCore:status>
    <baseRef>
      <platformCore:RecordRef type="invoice"></platformCore:RecordRef>
    </baseRef>
  </writeResponse>
  

• Cause: GetXMLString serializes an XML node but does not preserve attributes on the root element. When the source record's internalId is held as an attribute on the root NetSuite record node (for example, on the Invoice element), it is stripped from the resulting string and the Update activity sees an empty record reference.

• Resolution: Capture the source record's internalId separately, then add it back to the serialized XML before passing the payload to the Update activity:

  1. In the transformation script, assign the source internalId to a variable.
  2. Call GetXMLString to build the record XML.

  3. Use Replace to inject internalId="..." onto the root element. For an Invoice record:

     <trans>
     $invoiceInternalId = searchResponse$searchResult$recordList$record.Invoice$internalId;
     $MyRecord = GetXMLString([searchResponse$searchResult$recordList$record.]);
     $MyRecord = Replace($MyRecord, "<Invoice>", '<Invoice internalId="' + $invoiceInternalId + '">');
     </trans>
     

  4. Pass MyRecord to the next step.

Performance and record limits

Operations fail due to NetSuite API record limits

• Symptom: An operation using the NetSuite connector fails or processes fewer records than expected because the source data exceeds the per-call record limit imposed by NetSuite's API.
• Cause: NetSuite's API enforces size limitations on the number of records per request. When more records are sent in a single call than the limit allows, NetSuite rejects the excess.
• Resolution:
  1. Enable chunking on the operation under Operation options. When the source is a NetSuite activity, chunking splits the data during transformation rather than at retrieval. Each chunk is written to a temporary file and the files are combined into the final target after all chunks are processed.
  2. When the target is a NetSuite activity, each source chunk produces one target chunk, with the transformation applied separately to each. The resulting target chunks are then combined.
  3. For instructions and best practices, see Enable Chunking.
  4. For deeper reference, see Detailed chunking information.

Operations fail due to concurrent request limit

• Symptom: High-volume NetSuite operations fail with one of the following errors:
  • RESTlet requests: HTTP error code: 400 Bad Request / SuiteScript error code: SSS_REQUEST_LIMIT_EXCEEDED
  • Web services requests: ExceededConcurrentRequestLimitFault or ExceededRequestLimitFault
• Cause: NetSuite enforces concurrency governance per account, limiting the combined total of simultaneous web services and RESTlet requests. The limit depends on your service tier and the number of SuiteCloud Plus licenses. For example, Service Tier 1 with five SuiteCloud Plus licenses allows 65 concurrent requests (15 + (5 × 10)). Exceeding this limit causes NetSuite to reject the excess requests.
• Resolution:
  1. For private agents, set MaxNumberOfOperationThreads in the [OperationEngine] section of jitterbit.conf to a value that keeps the total concurrent NetSuite requests within your account's governance limit.
  2. Design operations to serialize requests where possible, or implement retry logic that waits and retries when the WS_CONCUR_SESSION_DISALLOWED response is received.
  3. Review your NetSuite client applications to confirm they handle the concurrency error codes gracefully.
  4. For further details on governance limits by tier, review the NetSuite 2017.2 release notes (pages 71–72).

Version and schema changes

Operations fail after updating the NetSuite WSDL URL

• Symptom: After updating the WSDL download URL in a NetSuite connection to reference a newer WSDL version, all operations using that connection's activities fail at runtime.
• Cause: Changing the WSDL download URL updates the connection but does not update the data schemas used by existing transformations. The transformations still reference schema fields from the previous WSDL version, which are incompatible with the new version.
• Resolution: To update the WSDL version correctly, follow the steps in Change the WSDL version. This procedure updates both the connection URL and the data schemas used by all affected activities, preventing runtime failures caused by schema mismatches.