NetSuite Error Messages
This article catalogs the error messages you may encounter in the iPaaS.com NetSuite integration and how to resolve them. Errors appear in Dashboard > Integration Monitoring > Error Logs in iPaaS.com when a record cannot be transferred. They are grouped below by the mapping collection flow that produces them.
Most common cause — incomplete go-live configuration. Many of the errors below ("… not found", "… is required", "… is invalid") occur because a shipped placeholder value was never replaced for your environment, or a required subscription setting was left unconfigured. The integration ships example values — a location, a subsidiary (Parent Company / HEADQUARTERS), a tax code (5), a discount item, a shipping-refund item, an inventory-adjustment account, and posting periods — that each subscriber must replace before go-live. Before troubleshooting an individual error, confirm you have completed the configuration: see the Placeholders and Control Settings to Review Before Go-Live checklist in NetSuite Known Limitations and the field reference in NetSuite Connections and Settings.
Some integration behaviors are intentional and do not produce an error (for example, a record skipped by a collection filter, or an optional attribute left unset because its custom field is empty). Those are documented in the relevant Mapping Documentation and NetSuite Known Limitations, not here.
Supported Flows
Error Collection
Sales Order (FROM iPaaS.com)
Customer could not be created
"Unable to create customer. This will prevent the transfer of the order."
Description: The order's customer could not be created in NetSuite, so the order cannot be created.
Resolution: Check the customer data on the source transaction (a customer requires at least a name, and a subsidiary on OneWorld accounts). Resolve the customer error, then re-transfer the order.
Possible duplicate sales order
"Unable to dynamically link to existing NetSuite sales order using {field}. This may result in duplicate sales orders."
Description: The integration could not match the incoming transaction to its existing NetSuite sales order using the configured Sales Order Duplicate Matching Field, so continuing could create a duplicate.
Resolution: Confirm the Sales Order Duplicate Matching Field subscription setting names a NetSuite field that holds your order number (for example
otherRefNum) and that the mapping populating it is stable. See NetSuite Connections and Settings.
Possible duplicate sales order line
"Unable to dynamically link to existing NetSuite sales order line. This may result in duplicate sales order lines in NetSuite."
Description: A line on the order could not be matched to its existing NetSuite line, which could duplicate the line.
Resolution: Re-transfer the order; if it persists, review the line's item and identifiers with iPaaS.com Support.
Line item not found in NetSuite
"Sku {sku} cannot be linked to a NetSuite item, so the transaction cannot be created using this line item."
Description: A line references a SKU that does not resolve to a NetSuite item.
Resolution: Create or correct the item in NetSuite so its SKU matches the source line, then re-transfer.
Gift certificate item not found
"Sku {sku} is not linked to a NetSuite item id."
Description: A gift-certificate or product line references a SKU that is not linked to a NetSuite item.
Resolution: Ensure the item (or gift certificate) exists in NetSuite with the matching SKU before transferring.
Gift certificate does not exist
"Gift Certificate does not exist in NetSuite."
Description: A gift-certificate redemption references a certificate that does not exist in NetSuite.
Resolution: Confirm the gift certificate exists in NetSuite (matched by its code) before redeeming it on a transaction.
Gift card payment is missing its identifier
"GiftCardId is missing or invalid in MethodInfo."
Description: A gift-card payment was sent without a valid gift-card identifier.
Resolution: Ensure the source payment includes the gift-card code/identifier.
Gift certificate quantity too high
"Gift card quantity cannot be greater than 1. NetSuite supports only one gift certificate per transaction line."
Description: A gift-certificate line has a quantity greater than 1.
Resolution: Sell multiple gift certificates as separate lines, each with quantity 1.
Matrix option does not exist
"{option} matrix option name does not exist in NetSuite. Please create it manually in the NetSuite portal."
Description: A variant option on the item is not defined as a matrix option in NetSuite.
Resolution: Create the matrix option (and its values) on the NetSuite item, then re-transfer.
Transaction date outside the posting period
"The transaction date is not within the date range of the selected posting period."
Description: The transaction's date does not fall in the NetSuite posting period the integration is configured to use.
Resolution: Use an open posting period for the transaction date. This often means a shipped posting-period placeholder was not replaced — see the go-live checklist in NetSuite Known Limitations.
Cash Sale & Cash Refund (FROM iPaaS.com)
These flows also raise the line-item, gift-certificate, and matrix-option errors listed under Sales Order above.
Location not found
"Failed to retrieve the location ID. The specified location name \"{name}\" is invalid or does not exist in NetSuite."
Description: The location name configured on the collection does not match a NetSuite location.
Resolution: This is almost always an unreplaced placeholder — the template ships an example location value. Set the location mapping to a valid NetSuite location name (see the go-live checklist in NetSuite Known Limitations).
Subsidiary not found
"Failed to retrieve the subsidiary ID. The specified subsidiary name \"{name}\" is invalid or does not exist in NetSuite."
Description: The subsidiary name configured on the collection does not match a NetSuite subsidiary.
Resolution: Unreplaced placeholder — the template ships
Parent Company(andHEADQUARTERSfor employees). Set the subsidiary mapping to a valid NetSuite subsidiary name (see the go-live checklist).
Missing transaction date
"The transaction date is missing. Please provide the transaction's created date."
Description: The posting-period check could not run because the transaction's created date was not supplied.
Resolution: Ensure the source transaction includes its created date before transferring.
Missing transaction date or posting period
"The transaction date or posting period is missing. Please provide both."
Description: The posting-period check requires both a transaction date and a posting period; one or both were empty.
Resolution: Confirm both the transaction date and the posting-period configuration are set (the template ships an example posting period that must be replaced).
Accounts Receivable not enabled (Cash Refund)
Description: A cash refund requires the NetSuite Accounts Receivable feature; without it, NetSuite cannot create the refund.
Resolution: Enable Accounts Receivable in NetSuite (Setup > Company > Enable Features > Accounting), then re-transfer. See NetSuite Known Limitations.
Invoice & Customer Payment
Invoice does not match its originating order
"Invoice validation failed: one or more invoice line items do not match the original sales order."
Description: Before an invoice is captured, the integration checks that its line quantities match the originating sales order; the check failed.
Resolution: Review the invoice and its originating order in NetSuite; an invoice that legitimately differs from its order will be stopped by this check.
Order and invoice totals do not match
"Order-Invoice total validation failed: Original order total ({expected}) does not match the invoice total."
Description: The originating order total (recorded on a NetSuite custom field when the order was created) does not match the invoice total.
Resolution: Confirm the order and invoice reconcile; investigate the discrepancy in NetSuite.
Line item not found in NetSuite
"Sku {sku} is not linked to a NetSuite item id."
Description: An invoice line references a SKU that does not resolve to a NetSuite item.
Resolution: Ensure the item exists in NetSuite with the matching SKU.
Payment could not be created
"Payment creation returned null or empty response."
Description: NetSuite did not return a valid response when creating the customer payment.
Resolution: Confirm the invoice exists in NetSuite and the payment does not exceed the invoice total; re-transfer. If it persists, contact iPaaS.com Support with the record.
Return Authorization / RMA (FROM iPaaS.com)
Originating order ID is required
"CreatedFrom_Id (Sales Order ID) is required for a Return Merchandise Authorization (RMA)."
Description: A return is created by transforming its originating sales order; that order's ID was not provided.
Resolution: Ensure the return references its originating sales order (which must already exist and be fulfilled in NetSuite).
At least one line item is required
"At least one line item is required to create a Return Merchandise Authorization (RMA)." (and the equivalent "…to update…")
Description: The return was sent with no line items.
Resolution: Include at least one return line.
Originating order could not be created
"Unable to create parent sales order. This prevents creating the return transaction."
Description: The originating sales order could not be created in NetSuite, so the return cannot be created.
Resolution: Resolve the originating order's transfer first (it must exist and be fulfilled), then transfer the return.
Originating transaction not found
"Parent transaction not found in source system."
Description: The return references an originating transaction that could not be found.
Resolution: Confirm the originating order exists and has transferred, then re-transfer the return.
Shipping-refund item is required
"ShippingRefundItemId is required when ShippingCost is provided."
Description: A return carries a shipping amount but no shipping-refund item is configured.
Resolution: Configure your shipping-refund item. The template ships a placeholder shipping-refund item id that must be replaced — see the go-live checklist in NetSuite Known Limitations.
Shipping-refund item is the wrong type
"ShippingRefundItemId '{id}' is invalid. Item must be of type 'OthCharge' with subtype 'Sale'. Found: Type='{type}', SubType='{subtype}'."
Description: The configured shipping-refund item exists but is not an Other Charge item with subtype For Sale.
Resolution: Use (or create) an Other Charge / For Sale item in NetSuite as the shipping-refund item.
Return could not be created
"Return Merchandise Authorization (RMA) creation failed because the NetSuite API did not return a valid response." (and the equivalent "…update failed…")
Description: NetSuite did not return a valid response when creating or updating the Return Authorization.
Resolution: Re-transfer; if it persists, contact iPaaS.com Support with the record and the originating order.
Product & Inventory
Item ID is required
"Item Id is required."
Description: A product is missing the SKU that becomes the NetSuite Item ID.
Resolution: Provide a SKU on the product before transferring.
Price levels are required
"Price levels are required."
Description: The product's pricing could not be resolved because no price level was available.
Resolution: Ensure the product has at least the default price level set.
Disabled product with variants
"Product transfers are not allowed when the product is disabled and has variants."
Description: A disabled (inactive) matrix product cannot be transferred while it still has variants.
Resolution: Re-activate the product, or remove its variants, before transferring.
Possible duplicate product or variant
"Unable to dynamically link to existing NetSuite product using iPaaS SKU {sku}. This may result in duplicate product records." (and the equivalent messages for product variants and variant options)
Description: The integration could not match the incoming product, variant, or variant option to its existing NetSuite record, which could create a duplicate.
Resolution: Confirm the SKU / option values match the existing NetSuite item; re-transfer once aligned.
Product could not be created
"Unable to create the product. This will prevent the transfer of the product." (and "Unable to create the product for inventory…" on the inventory flow)
Description: The product could not be created in NetSuite, so dependent transfers (including inventory) cannot proceed.
Resolution: Review the product's required fields (SKU, units type, and subsidiary on OneWorld), resolve the error, and re-transfer.
NetSuite Account Name is empty (inventory adjustment)
"The NetSuite Account Name custom field is empty."
Description: An inventory-adjustment transfer reads the account from the NetSuite Account Name custom field, which was empty.
Resolution: Populate the NetSuite Account Name custom field with a valid NetSuite account name. (On the inventory-adjustment children, the account ships as the placeholder Inventory Adjustment — see the go-live checklist.)
Inventory SuiteQL table is not configured
"Preset (Inventory SuiteQL Table Name) is null or empty. It must be specified in the subscription settings in order to query inventories."
Description: The integration queries inventory through a SuiteQL table whose name is set by a subscription preset that was left empty.
Resolution: Set the Inventory SuiteQL Table Name preset in the NetSuite subscription's Subscription Settings in iPaaS.com.
No bins available with Use Bins enabled
"No bins available for item {itemId}, but the Use Bins field is set to True."
Description: Bin-managed inventory is enabled (the USE BINS setting), but the item has no bins.
Resolution: Confirm the item is bin-managed in NetSuite, or disable the USE BINS setting if this item should not use bins.
Matrix option does not exist
"{option} matrix option name does not exist in NetSuite. Please create it manually in the NetSuite portal."
Description: A variant option is not defined as a matrix option on the NetSuite item.
Resolution: Create the matrix option and its values on the NetSuite item, then re-transfer.
Customer (FROM iPaaS.com)
Possible duplicate customer
"Unable to dynamically link to existing NetSuite customer using email address. This may result in duplicate customer records."
Description: The integration could not match the incoming customer (or company) to an existing NetSuite record by email, so continuing could create a duplicate.
Resolution: Confirm the customer's email is present and consistent; keep the email mapping stable once customers exist (see NetSuite Known Limitations).
Employee & TimeBill (FROM iPaaS.com)
Employee could not be created
"Unable to create the employee in NetSuite: {detail}"
Description: A time bill references an employee that could not be created in NetSuite.
Resolution: Resolve the employee transfer first (name, subsidiary, and currency are required), then transfer the time bill. Note the subsidiary is resolved by name and ships as the placeholder HEADQUARTERS — see the go-live checklist.
Possible duplicate time bill
"Unable to dynamically link to existing NetSuite timeBill using externalId. This may result in duplicate timebill records."
Description: The time bill could not be matched to its existing NetSuite record, which could create a duplicate.
Resolution: Re-transfer; if it persists, review the time bill's identifiers with iPaaS.com Support.
Location and employee in different subsidiaries
"The selected Location and Employee belong to different subsidiaries. Please choose a Location that is associated with the same subsidiary as the Employee."
Description: The location on the time bill belongs to a different subsidiary than the employee.
Resolution: Choose a location in the employee's subsidiary.
Invalid location name format
"Invalid location name. Provide the parent name and the location name separated by ' : ' when the location has a parent."
Description: A hierarchical location requires the
Parent : Locationformat.Resolution: Enter the location as
Parent Name : Location Namewhen the location has a parent.
Connection and Authentication
These errors are not specific to one mapping flow — they can affect any transfer when the NetSuite connection, authentication, or a query fails.
NetSuite query failed
"SuiteQL API call failed: {details}"
Description: A query to NetSuite (SuiteQL) returned an error from the NetSuite API.
Resolution: Review the details in the error; common causes are an authentication/permissions issue or a NetSuite-side limit. Confirm the connection is configured per NetSuite Connections and Settings; if it persists, contact iPaaS.com Support.
Getting Help
If an error is not listed here or the resolution does not clear it, contact iPaaS.com Support through the support portal, including the error text and the affected record from Dashboard > Integration Monitoring > Error Logs. First confirm the go-live configuration is complete — most "not found" / "is required" errors are caused by an unreplaced placeholder or an unconfigured subscription setting (see the Placeholders and Control Settings to Review Before Go-Live checklist in NetSuite Known Limitations).