NetSuite Connector Troubleshooting

Error Message

NetSuite Warning: Warning received from NetSuite for record record: (Error Received during NetSuite Update

Code: INVALID_SUB
Type: ERROR
Message: The subsidiary restrictions on this record are incompatible with those defined for location: 00 YourLocation. Subsidiary access on this record must be a subset of those permitted by the location.

Sync Process

Any

Cause

The default Subsidiary is invalid for the default location set in NetSuite Connector Preferences, or the combination of the defaults and a Subsidiary or Location set on the Customer Account or Zuora Product Rate Plan Charge is invalid.

Resolution

Subsidiary, Location, Class and Department must be reconciled with NetSuite and configured properly within NetSuite Connector Preferences and their respective custom fields within Zuora.

Error Message

NetSuite Warning: A warning was received from NetSuite for the record: (Error Received during NetSuite Update)

Code: USER_ERROR
Type: ERROR
Message: Please enter value(s) for: Subsidiary.

Sync Process 

Any

Cause

The error occurred because no specific "subsidiary" type was selected during the update process in NetSuite.

Resolution

Ensure to select the "subsidiary" type when encountering issues related to subsidiaries. Alternatively, if the issue involves a missing department selection, choose the appropriate department. This proactive approach ensures accurate record creation in NetSuite.

Error Message

Error executing Netsuite operation: Only one request may be made against a session at a time.

Sync Process

Any

Cause

The Integration user (Web Services User) does not have the field 'Concurrent Web Service User' set to TRUE on it's Employee record.

Resolution

Please review the steps for configuring a NetSuite Web Services User for use with NetSuite Connector in CreateaNetSuite Connector User.

Error Message

NetSuite Warning: Warning received from NetSuite for record record: (Error Received during NetSuite Update

Code: INSUFFICIENT_PERMISSION
Type: ERROR
Message: You do not have permissions to set a value for element field_name due to one of the following reasons: 1) The field is read-only; 2) An associated feature is disabled; 3) The field is available either when a record is created or updated, but not in both cases.
) null

Sync Process

Any

Cause

1. General: The most common cause is that the field name referenced is not configured to be displayed on the preferred form for the given NetSuite object.
2. General: The default role for the NetSuite user configured in NetSuite Connector does not have a preferred form that displays the field referenced in the error message.
3. General: The default role for the NetSuite user configured in NetSuite Connector does not have permissions to edit certain custom Zuora fields.
4. Initialization, field name taxSchedule: In the NetSuite Connector Sync Preferences, a Default NetSuite Tax Schedule value was entered but the client’s NetSuite account is not configured to use Tax Schedules (Advanced Taxes are disabled). To confirm this, in NetSuite navigate to Setup > Company > Enable Features > Accounting tab > Advanced Features.
5. Initialization, field name taxitem: In the NetSuite Connector Sync Preferences, a Default Tax Code value was entered but the client’s NetSuite account is not configured correctly. To confirm this, in NetSuite navigate to Setup > Accounting > Set Up Taxes > United States (if multiple currencies) and look for the Per-Line Taxes on Transactions setting. This should be disabled (unchecked).
6. Zuora Invoice, field name taxitem: The client has NetSuite International Edition but NetSuite Connector is not configured accordingly.
7. Zuora Invoice, field name deferrevrec: This error is caused by one of the following:
   • The associated NetSuite Item is not configured with a Deferred Revenue Account.
   • A Revenue Recognition Template is configured in Zuora for an Inventory type item. Inventory items cannot be amortized. Remove the Revenue Recognition related values on the Zuora Product Rate Plan Charge.
   • The Delay Rev. Rec. or Revenue Recognition Schedule field is not configured to be displayed on the preferred Invoice form or Credit Memo form (for negative Zuora invoices) in NetSuite.
8. Customer, field name autoname: If Zuora is the Customer Master, there is a discrepancy between the NetSuite Connector Customer Account mapping preference and the configuration within NetSuite, which is preventing the sync from populating the Zuora Customer Account Number/Name to the NetSuite Customer ID field when creating/updating the record.
9. Customer, field name subsidiary: In NetSuite OneWorld editions using subsidiaries, if the Consolidated Payments feature is enabled NetSuite does not allow a subsidiary to be explicitly set for new child customer records. The subsidiary is inherited from the parent customer record.

Resolution

1. Edit the preferred form in NetSuite for the given object and ensure the field in question is set to be displayed on the appropriate screen. Note the preferred form can be set "globally" or for a specific role (see next item). See Configure NetSuite Forms for more information.
2. Verify the default role for the NetSuite user by logging into NetSuite as that user, clicking the dropdown by the user name in the upper right corner, and choosing View All Roles. Then verify that role's preferred form is one that is configured to display the field referenced in the error message.
3. Some key custom fields come preconfigured in the NetSuite Connector bundle with the edit permission restricted to the Administrator role. If you wish to use a different or custom role for the NetSuite Connector integration user, be sure to modify the access permissions accordingly to allow the different role to be able to modify the field values. The custom field access permissions can be found within NetSuite under Setup > Customization > Entity/Item/Transaction Body/Transaction Column Fields > edit field > Access tab.
4. Remove the "Default NetSuite Tax Schedule" value in the Integrations Manager's Sync Preferences.
5. Disable the Per-Line Taxes on Translations NetSuite setting.
6. Within NetSuite Connector, set the Advanced Setting Use Standard Invoice Sync to "Yes - NetSuite Int'l Edition". This will suppress the syncing of tax-related fields for Zuora transactions.
7. For this case, use one of the following methods to resolve the error:
   • If the associated NetSuite Item is not configured with a Deferred Revenue Account, if the Charge has already been synced, edit the Item record directly in NetSuite to select the Deferred Revenue Account. (The Deferred Revenue Template field is optional.)
   • If the Delay Rev. Rec. or Revenue Recognition Schedule field is not configured to be displayed on the preferred Invoice form or Credit Memo form (for negative Zuora invoices) in NetSuite, edit the Preferred Invoice form or Credit Memo form in NetSuite and ensure that the Delay Rev. Rec. field is set to be displayed in the Columns section.
8. Modify the NetSuite Connector preferences and/or NetSuite configuration to align with how you want the Customer ID mapping behavior to work. If Zuora is the Customer Master and you choose to use a value from the source record for the Customer Account Number Mapping, if Auto-Generated Numbers are enabled for Customers in NetSuite, be sure to enable Allow Override in NetSuite. Additionally if you want to sync both new and modified records, you must also enable Update in NetSuite (go to Setup > Company > Auto-Generated Numbers). See Configure Sync Preferences for more information.
9. Disable the Consolidated Payments feature within NetSuite: Setup > Company > Enable Features > Accounting tab > Advanced Features section. Consolidated payments are not supported by NetSuite Connector because it prevents the reconciliation of NetSuite payments to specific Zuora invoices.

Error Message

Process is Already Running

Sync Process

Initializing

Cause

The sync is already running. Only one instance of the sync may run at a given time. You may see this warning message if a previous sync is still running when the next sync is scheduled to run or if the manual Run Now button was clicked multiple times in close succession.

Resolution

Wait for the current sync to complete and then run the sync again or wait for the next scheduled sync. Records already in progress will continue to sync as normal.

Error Message

Error executing Netsuite Command: Unable to lookup web services domain.

Sync Process

Initializing, Any

Cause

Invalid NetSuite password configured in Integration Setup.

Sync Process

Resolution

Modify the Integration Preferences > Connection Information and re-enter your NetSuite password.

Error Message

Error executing Netsuite Command: Error executing Netsuite operation. You have entered an invalid email address or account number

OR

Error executing Netsuite Command: Unable to lookup web services domain.

Sync Process

Initializing, Any

Cause

Invalid NetSuite user name or account number configured in Integration Setup.

Resolution

Modify the Integration Preferences > Connection Information and re-enter your NetSuite credentials.

Error Message

First document failure: [FAIL] Unknown failure invalid type: Export

Sync Process

Any

Cause

Data source permission is not enabled for the Zuora tenant.

Resolution

Enable data source permission for the Zuora tenant.

Error Message

First document failure: Unable to login

OR

Invalid login. User name and password do not match.

Sync Process

Any

Cause

1.  Unable to log into Zuora.
2. The Zuora application or web service is temporarily unavailable.  

Resolution

1.  Modify the Integration Preferences > Connection Information, re-enter your Zuora credentials, and try logging in again. Make sure the Zuora Web Service Site matches a correct endpoint:
   • https://www.zuora.com/apps for the US Production
   • https://apisandbox.zuora.com/apps for the US API Sandbox
   • https://eu.zuora.com/apps for the EU Production
   • https://sandbox.eu.zuora.com/apps for the EU Sandbox
2. Try to log into Zuora application UI.

Error Message

Process terminating -- some documents reached an exception which is set to halt all documents: There were warnings during the sync. Please review the Process Log for details.

Sync Process

Any

Cause

This is a summary error notification, not the actual error message needed for troubleshooting.

Resolution

Look for other error messages earlier in the Process or Document logs that contain a specific error message.

Error Message

No records found to sync.

Sync Process

Any

Cause

No records of the given type (for example, Account, Charge, or Invoice) were found that match the sync criteria.

Resolution

Confirm that the to-be-synced record meets the sync criteria. If it does not, modify the record to meet the sync criteria.

Error Message

First document failure: Error invoking soap operation; Caused by: The server sent HTTP status code 503: Service Temporarily Unavailable

Sync Process

Any

Cause

Sync cannot connect to Zuora or NetSuite application endpoints. Application may currently be unavailable due to maintenance downtime or network problems.

Resolution

Wait several minutes and retry the sync. If the problem persists, contact the appropriate vendor (NetSuite or Zuora) to inquire about application availability.

Error Message

First document failure: Unable to get internalId for script id: customlistzuorabillcycleday

Sync Process

Customer

Cause

Required NetSuite configuration has not been performed.

Resolution

In NetSuite, go to Setup > Company > Enable Features > SuiteFlex tab, and enable Server SuiteScript (accept agreement).

Error Message

Netsuite warning: nullWarning received from NetSuite for record "ZD00070743 Indigovern - 20220429 000000.000"

Code: SSS_USAGE_LIMIT_EXCEEDED
Type: ERROR
Message: Script Execution Usage Limit Exceeded

Sync Process

Any

Cause

This is a limitation on the NetSuite side. NetSuite imposes restrictions on its API calls.

Resolution

Review and optimize the script execution to stay within NetSuite's API usage limits. For guidance on managing and optimizing API calls, refer to NetSuite's API documentation.

Error Message

NetSuite Warning: Warning received from NetSuite for record record: (Error Received during Netsuite Update

Code: RCRD_DSNT_EXIST
Type: ERROR
Message: There are no records of this type.
) null 

Sync Process

Zuora account or charge to NetSuite

Cause

The Integration ID value is populated on the Zuora record but does not match a valid NetSuite internal ID, preventing the from being able to update the record. The invalid Integration ID may have been populated manually by accident, reference a record that no longer exists, or reference a record from a different NetSuite environment.

Resolution

Locate the corresponding record in NetSuite. If found, copy the NetSuite internal ID from the browser’s URL, paste into the Zuora record’s Integration ID, and run the sync. If not found, simply clear out the Zuora record’s Integration ID and run the sync to create a new record in NetSuite.

Error Message

Inventory items must have a positive amount.

Sync Process

Zuora Invoice (negative invoice) to NetSuite

Cause

NetSuite does not allow Inventory-type items to have negative amounts. Remember that the Zuora invoice item amounts are negated when syncing to NetSuite Credit Memos.

Resolution

Edit or regenerate the Zuora Invoice and adjust amounts for Charges with different item types. This means any Inventory-type Charges on a "negative invoice" must be edited to negative amounts.

Error Message

NetSuite Warning: Warning received from NetSuite for record record: (Error Received during Netsuite Update

Code: INVALID_KEY_OR_REF
Type: ERROR
Message: Invalid account reference key key for customer customer.
) null 

Sync Process

Zuora Refund to NetSuite

Cause

The GL Account reference for a Refund must match that of the original Payment. The integration retrieves the GL Account from the NS Payment Method so if the account was manually changed between when the Payment and Refund were synced, this error could result.

Resolution

Manually edit the NS Payment or Payment Method as necessary to reconcile the account references.

Error Message

NetSuite Warning: Warning received from NetSuite for record record: (Error Received during Netsuite Update

Code: INVALID_KEY_OR_REF
Type: ERROR
Message: Invalid account reference key key for entity entity.
) null 

Sync Process

Zuora Refund to NetSuite

Cause

The Zuora Product Rate Plan Charge must have an assigned Accounting Code. That code must also exist for the NetSuite Item GL code.

Resolution

Make sure that the Zuora Product Rate Plan Charge has an assigned Accounting Code, and that it also exists for the NetSuite Item GL code.

Error Message

Warning received from NetSuite for record "INV00000001": (Error Received during Netsuite Update

Code: USER_ERROR
Type: ERROR
Message: TypeError: Cannot read property "length" from null (AVA_Functions.js#1)
) null 

Sync Process

Invoice

Cause

AVATAX users must specify a NetSuite Default Tax Code in the integration settings.

Resolution

Assign a NetSuite Default Tax Code in the Sync Preferences.

Error Message

Zuora Warning: Warning received from Zuora for record record: SubscriptionData.SubscriptionRatePlanData[0].ProductRatePlanId is invalid.

Sync Process

NetSuite Sales Order

Cause

One of the Zuora items referenced on the NetSuite Sales Order does not represent a Zuora Rate Plan record. It may represent a Zuora charge by accident.

Resolution

Review the NetSuite Sales Order and remove any Zuora items that do not represent a Zuora Rate Plan. If you cannot determine the item type from the its name, open the Item record and look at the Zuora Type field. The type should be RATE_PLAN.

Error Message

Error Code: INVALID_KEY_OR_REF
Type: ERROR
Message: Invalid CUSTBODYZUORASYNCUPDATES reference key

Sync Process

NetSuite payments to Zuora

Cause

This Netsuite error occurs when you sync the Netsuite payment object to Zuora. This error is due to the edit permission not being enabled in the custom list.

Resolution

Enable edit access to the "Custom List" permission.

Error Message

NetSuite Warning: Warning received from NetSuite for record "INVxxxxxxx": (Error Received during Netsuite Update)

Code: MISSING_ACCT_PRD
Type: ERROR
Message: You are attempting to create an amortization or revenue recognition schedule outside the range of available accounting periods. Please adjust the periods on this transaction or go to Setup > Accounting > Manage Accounting Periods to set up more periods. ) 

Sync Process

Zuora Invoice

Cause

1. One or more of the Revenue Recognition Schedules referenced on one or more Zuora Invoice Item Charges extends beyond the list of Accounting Periods currently configured in NetSuite. For example, the Revenue Recognition Schedule is for 24 months but you have not created Accounting Periods two years out yet.
2. Alternatively, this error may also occur if the Revenue Recognition Template is configured with a Start Offset that falls outside the Revenue Recognition Start and End Dates for a given Item/Charge.

Resolution

1. Configure additional Accounting Periods as necessary and try again. Within NetSuite, go to Setup > Accounting > Manage Accounting Periods.
2. Review the Revenue Recognition Template configuration within NetSuite (Lists > Accounting > Revenue Recognition Templates), verify the Revenue Recognition Start and End Dates encompass any Start or Period Offsets, adjust the Revenue Recognition dates on the Zuora Invoice Item accordingly, and resync the invoice.

Error Message

No error message is displayed.

Sync Process

Netsuite payments are intended to sync to Zuora.

Cause

Payments that have a journal applied to them are not supported by the connector, resulting in a failure to sync.

Resolution

Prior to syncing again, undo the journal entry associated with the affected payment.

Error Message

No record details found in memory for RECORD_ID '1234'.

Sync Process

NetSuite Customer

Cause

This typically means the NetSuite customer references a parent customer that is not set to sync or there was an unexpected sync error and therefore cannot find a reference ID for that parent record when attempting to create/update the Zuora Customer Account.

Resolution

Make sure all of the given NetSuite customer’s parent records are set to Sync to Zuora=Yes and try again.

If issue persists, review the sync logs for another warning or error related to the parent customer record. If found, take appropriate corrective action to get the parent customer to sync successfully. 

Error Message

NetSuite Warning: Warning received from NetSuite for record "record": (Error Received during Netsuite Update

Code: INSUFCNT_NUM_PRDS_FOR_REV_REC Type: ERROR Message: Not enough accounting periods in range specified for revenue recognition. ) null 

Sync Process

Invoice

Cause

If Accounting Periods are enabled (Setup > Company > Enable Features > Accounting), you must create Accounting Periods to accommodate the length of the Revenue Recognition Schedule referenced on the Invoice Items.

For example, if your Revenue Recognition Schedule extends from 2011 into 2013, you will need to make sure Accounting Periods exist for 2011, 2012, and 2013. 

Resolution

Contact your NetSuite administrator to create additional Accounting Periods. Within NetSuite, go to Setup > Accounting > Manage Accounting Periods. The most common need is to configure Set Up Year for a future fiscal year.

Error Message

Warning received from NetSuite for record "record": (Error Received during Netsuite Update Code: REV_REC_TMPLT_DATA_MISSING Type: ERROR Message: One or more line items on this transaction have Variable Revenue Recognition Templates, but do not have the required project also populated. Please either change the Template for these items or indicate which project will be used to schedule the recognition of revenue.

Sync Process

Invoice

Cause

When syncing Invoice Charges with references to NetSuite Projects and variable Revenue Recognition Templates, there are a number of record configurations that must align.

Resolution

Check the following:

1. The associated Zuora Subscription has the NetSuite Project field set to a valid internal ID (not the name) of a NetSuite Project.
2. The relevant Zuora Charges have a Revenue Recognition Template selected AND have the NetSuite Revenue Recognition Template Type field set to Variable.
3. The reference Revenue Recognition Template exists in NetSuite with the same name and is configured as a Variable type. 

Error Message

Error executing NetSuite operation. An unexpected error occurred. Error ID: Error ID

Sync Process

Initialization, any

Cause

1. Invalid NetSuite credentials (including leading/trailing whitespace around values, such as Account ID)
2. Invalid NetSuite request
3. Temporary internal processing error within NetSuite

Resolution

1. Modify the Integration Preferences > Connection Information, carefully re-enter your NetSuite credentials (make sure to not copy leading or trailing whitespace if copy-and-pasting values), and try again.
2. Try to obtain the failed NetSuite request and response data from within NetSuite: Setup > Integration > Web Services Usage Log > adjust time filters and look for recent FAILED actions. Download and forward the Request and Response data to Zuora Global Support.
3. In many cases simply retrying the sync at a later time resolves the issue. If the error persists, download and forward the Request and Response data and raise to NetSuite support for further investigation.

Error Message

Error executing Netsuite operation. Only one request may be made against a session at a time

Sync Process

Any

Cause

This NetSuite error occurs when more than one API call is made to NetSuite at the same time with the same user credentials. Typically, this means the user has other integrations with NetSuite outside of the NetSuite Connector solution.

Resolution

• Attempt to coordinate the schedules of the NetSuite Connector sync with the custom integrations to avoid them running at the same time.
• Use different credentials for NetSuite Connector.
• Contact NetSuite to learn more about purchasing concurrent connection licenses.

Error Message

Code: INVALID_KEY_OR_REF
Type: ERROR
Message: Invalid internalId reference key ?

Sync Process

Any

Cause

This error occurs due to an invalid internalId reference key in the NetSuite integration ID field.

Resolution

To resolve this issue, set the NetSuite integration ID field to blank. Do not manually update the integration field, as the connector will automatically manage these updates once the sync process is complete.

Error Message

Warning received from Zuora for record "record": (INVALID_VALUE) Apply amount can not be larger than the balance of invoice.

Sync Process

Payment

Cause

The error indicates that for the specified account, the apply amount cannot be larger than the balance of invoice. This can occur when an account in Zuora has an invoice that has already been paid. If in NetSuite the payment is greater than that any remaining balance (or greater than 0 if the invoice has been fully paid), the payment cannot be synced to Zuora. 

Resolution

• Remove the payment in NetSuite.
• Remove the external payments under the accounts and restart the sync.

Error Message

Nested connector call returned more than 1 document.

Sync Process

NetSuite Payment

a. Cause

A previous sync error has left a payment in an intermediate status resulting in the creation of duplicate draft payment records in Zuora.

a. Resolution

1. In NetSuite, look for Payments with IntegrationStatus="Creating Payment..." or "Error Creating Payment". Note the internal ID of the record(s). (Tip: You can find the NetSuite internal ID by viewing the record in NetSuite and looking at the browser URL.)
2. In Zuora, look for corresponding payments already in Zuora where Integration ID matches the NetSuite internal ID. You should find two or more Zuora Payments.
3. In Zuora, cancel the Payments and clear out the Integration ID values.
4. In NetSuite, clear the Integration Status field on the payment.
5. Run the sync again.

b. Cause

Customer accounts failed to update 

b. Resolution

You may intend to recreate an account in NetSuite with the same ID by adding ‘-1’ to the account ID in NetSuite and delete the Zuora integration ID in the account after syncing it from Zuora to NetSuite, while changing account details that require recreation.

But, when the Account lacks integration id and status, the Connector will create a new customer in Netsuite with the Zuora id. The connector’s validation process will trigger a warning if the integration status of the customer’s Zuora account is Sync Complete but no integration ID is found, indicating “Integration ID field is mandatory. Please try again by entering a value”.

If your Zuora account integration status shows an error while creating or updating a customer, the connector will take the following action: 

1. Make a call to Netsuite and retrieve the internal ID from Zuora ID. 
2. Check if the internal ID already exists in Netsuite, and mark the account as Sync Complete. 

Limitations

• Zuora does not detect any errors related to Nested connector call that returned more than 1 document. If the issue resurfaces for your accounts, you can solve it by removing the integration status field and setting it to empty.
• The connector will generate an error message “Nested connector call returned more than 1 document” if multiple accounts are created with the same Zuora ID.

Error Message

(INVALID_VALUE) Only Payments with the Status Processed can be created as of version 64 of the API.

Sync Process

NetSuite Payment to Zuora Payment Sync

Cause

The WSDL version specified in the Integration Connection is higher than 69.0. Account sync is incompatible with the new date format for WSDL version 69 or above.

Resolution

Roll back the WSDL version to 63.0 or prior and re-run the sync.