Requirements
Integrations Platform: M-Bridge
Subscription Plan: Enterprise
User Permissions: Account Administrator (configurable)
Overview
Events that fail to process will generate an exception link on M-Bridge. The exception link will be indicated by an exclamation mark within the M-Bridge banner, which means that there are new Exceptions/Events since the last time the page was loaded.
TIP
Exceptions are displayed in reverse-chronological order with the most recent at the top. They can be filtered by Integration or by Keyword.
For each Exception Type, the following information displays:
- Last Occurrence [Date and Timestamp]
- Integration
- Message
- Occurrences [Number of Events with this Exception]
- Errors [View Events]
- Actions [Manage or Dismiss Events]
The following list includes descriptions for the Exception [#] [Title], Issue, Scenario, Potential Cause, and Resolution fields for each Exception Table within this article. These Exceptions are common issues that can happen within the NetSuite integration. Each common Exception is numbered and provided with a troubleshooting table that contains sections to give more information and insight:
- Exception [#] [Title]: This is the numerical value and title of each Exception located at the top of each issue. You can find each numbered Exception within an ordered list on the right side of this article under In This Article. Within this article, an Event or Exception may be used interchangeably.
- Error Text: This section provides the error text as it is displayed within the integration platform verbatim.
- Scenario: This section describes the type of software scenario that is involved with each Exception. For example, if the Exception is taking place from Kantata to NetSuite, NetSuite to Kantata, Tasks from Kantata to NetSuite, etc.
- Potential Cause: This section lists what could be causing the Exception to happen.
- Resolution: This section itemizes possible processes and solutions to resolve the Exception.
TIPS FOR EXCEPTION RESOLUTION
- Re-emit: Re-emitting an event or exception will make an exact copy of that event’s data and attempt to process it again. A Re-emitted event or exception will not contain any new or updated data from the source system.
- Resync: Resyncing the scenario after an update will create a new event with the new or updated data and attempt to process and sync that to the target system.
- Resolve: If Resolving the error requires a change in the source system then the scenario must be Resynced after the update is made. If Resolving the error requires a change in the target system or a change in the mapping tables, then the event can be Re-emitted.
Troubleshooting Common Exceptions
Exception (1) A User Can't Set Billable Value
Error Text |
You do not have permissions to set a value for element is billable 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. |
Scenario |
|
Potential Cause |
|
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Add a Customer to a NetSuite Project
Note: If the NetSuite project has no customer, the customer can't be added via the integration after the project has been created in NetSuite. Additionally, the NetSuite task must be marked as Billable and the Expense category must be mapped within the mapping tables.
Mark the Task as Billable Instead of Non-Billable
Mark the Time Entry as Billable Instead of Non-Billable
|
Exception (2) Invalid Customer Reference Key for Employee
Error Text |
Invalid customer reference key [#######] for employee [#####]. |
Scenario |
|
Potential Cause | The employee is not yet on the project or task in NetSuite that this time entry is being entered for. - or - The project in NetSuite status is Inactive. |
Resolution |
For resolution, you may need to complete one or all of the items within the following process based on circumstance: Ensure NetSuite has the Most Recent Assignments
Note: The [#] after the Customer Reference Key is the Internal ID of the Project in NetSuite. The [#] after Employee is the Internal ID of the Employee in NetSuite.
|
Exception (3) Invalid Customer Reference Key for Entity
Error Text |
Invalid customer reference key [#######] for entity [#####]. |
Scenario |
|
Potential Cause |
The project that this time entry or expense is being synced to is not yet in NetSuite. -or- The project that this time entry or expense is being synced to has been made Inactive in NetSuite. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Ensure NetSuite has the Most Recent Assignments
Note: The [#] after the Customer Reference Key is the Internal ID of the Project in NetSuite. The [#] after Entity is the Internal ID of the Customer in NetSuite.
Reactivate a Project and Sync to NetSuite:
-or- If you can't Re-Active the project, confirm that the project should be syncing to NetSuite.
|
Exception (4) Invalid Customer Reference Key for Subsidiary
Error Text |
Invalid customer reference key [#######] for subsidiary [#####]. |
Scenario |
|
Potential Cause | The customer is not available to the subsidiary within the project that is being created. |
Resolution |
For resolution, you may need to complete one or all of the following items within this process based on circumstance: Confirm Information in Kantata Custom Fields
Note: The [#] after the Customer Reference Key is the Internal ID of the Customer in NetSuite. The [#] after the Subsidiary is the Internal ID of the Subsidiary in NetSuite.
|
Exception (5) Invalid Job Resource Reference Key
Error Text |
Invalid jobresource reference key [#######]. |
Scenario |
|
Potential Cause | The employee in NetSuite doesn't have the Project Resource box checked on their Employee Record. |
Resolution |
For resolution, complete the following process: Enable the Project Resource on an Employee Record
Note: The [#] after the Reference Key refers to the Internal ID of the Employee in Netsuite.
|
Exception (6) Invalid Resource Reference Key
Error Text | Invalid resource reference key [####]. |
Scenario |
|
Potential Cause | The integration is attempting to assign an employee to a task when that employee is not a resource on the project. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Enable the Project Resource on an Employee Record
Note: The [#] after the Reference Key refers to the Internal ID of the Employee in Netsuite.
Resync and Re-emit the Project Exceptions
Note: Complete the following if you are using the projects from Kantata > NetSuite.
|
Exception (7) Invalid Parent Reference Key
Error Text | Invalid parent reference key [#####]. |
Scenario |
|
Potential Cause |
The project in Kantata has the GL Project ID field filled out incorrectly. -or- The NetSuite project was deleted or its status is Inactive. This means that the Task scenario is trying to update a task that is on the deleted or inactivated project. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Confirm NetSuite Project Details
Note: The [#] after the Parent Reference Key is the Internal ID of the Project in Netsuite.
Confirm Kantata Project Details
Tip: After confirming the details within NetSuite are correct, please confirm accuracy from the Kantata side.
|
Exception (8) Unit Cost Values Error
Error Text | Please enter value(s) for: Unit Cost. |
Scenario |
|
Potential Cause | Employee(s) have empty Labor Cost fields on their Employee Record within NetSuite. |
Resolution |
For resolution, complete the following process: Verify and Enter Labor Cost Fields Across Software
|
Exception (9) Location Values Error
Description | Error: Please enter value(s) for: Location. |
Scenario |
|
Potential Cause | The target record or transaction in NetSuite has Location as a required field. This field is not being populated by the integration. |
Resolution |
For resolution, you may need to complete one or all of these processes: If the Location Doesn't Need to be Mandatory
If the Error is on a Timesheet or Expense Report
If the error is on a NetSuite Invoice
|
Exception (10) Mapping Kantata ID User Errors
Error Text |
No users mapping for Kantata ID [#######] -or- Kantata users [#######] are not mapped to NetSuite users. |
Scenario |
|
Potential Cause |
The User ID Number does not have a valid mapping on the User Mapping Table within the integration platform. |
Resolution |
For resolution, complete the following process: Update Valid User Mapping in Kantata
|
Exception (11) Mapping External User ID Errors
Error Text | No users mapping for External ID [######]. |
Scenario |
|
Potential Cause |
A NetSuite Employee is not mapped to a Kantata user. -and/or- A client is using Generic Resources in NetSuite. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Find and Update Valid User Mapping in NetSuite
Update the Generic Resources in NetSuite
|
Exception (12) Transaction Subsidiary Not Valid for Entity
Error Text | Transaction subsidiary [#####] is not valid for entity [####]. |
Scenario |
|
Potential Cause | The subsidiary for the invoice you're trying to create does not match the subsidiary of the project in NetSuite. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance:
Note: The [#] after Subsidiary is the NetSuite Subsidiary Internal ID. The [#] after Entity is the NetSuite Project ID.
Note: If multi-subsidiary customers are enabled, the invoice will only sync to the Primary Subsidiary or the Customer. This is a NetSuite API limitation.
|
Exception (13) Invalid Employee Reference Key
Error Text | Invalid employee reference key [####]. |
Scenario |
|
Potential Cause | This NetSuite error occurs when the mapped employee has an Inactive status. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance: If the NetSuite Employee Status is Active
If the NetSuite Employee Status is Inactive
|
Exception (14) Invalid Currency Reference Key for Subsidiary Null
Error Text | Invalid currency reference key [##] for subsidiary <NULL>. |
Scenario |
|
Potential Cause |
The Subsidiary custom field on the project in Kantata is blank. -or- The Kantata Project Currency doesn't match the NetSuite Subsidiary Currency. -or- The project was synced with [X] currency to a customer that didn't have [X] currency assigned to them as an available currency. |
Resolution |
For resolution, complete the following process: Resync the Project to NetSuite
Note: Ensure the Kantata project can sync to NetSuite.
|
Exception (15) Invalid Unit Cost for Job Resource
Error Text | Invalid Unit Cost for jobresource [#######]. |
Scenario | - |
Potential Cause |
An employee in NetSuite doesn't have a valid Labor Cost on their Employee Record. -or- The status of the NetSuite Employee Record is Inactive. |
Resolution |
For resolution, complete the following process: Verify the Employee Record and Labor Cost Fields
|
Exception (16) Missing Fields Causing Failed Invoices
Error Text | undefined method `[]' for nil:NilClass. |
Scenario |
|
Potential Cause |
The GL Task Item ID custom field may be blank for one or more tasks on an invoice. -or- The Subsidiary custom field is blank on the workspace. |
Resolution |
For resolution, complete the following process: Update the Empty Fields within the Invoice
|
Exception (17) Local Record Existing Time Bill Error
Error Text |
{"errors"=>[{"type"=>"system", "message"=>"Not found"}]} -or- {"errors"=>[{"type"=>"system", "message"=>"Not found"}]} -or- Not Found. |
Scenario |
|
Potential Cause | "Not Found" errors occur mostly when the integration is looking for information from an Archived workspace. |
Resolution |
For resolution, complete the following process: Update the Empty Fields within the Invoice
Unarchive the Workspace and Re-emit the event. -or- If the Exception data doesn't sync: Dismiss this error. |
Exception (18) Expense Categories Not Mapping for External ID
Error Text | No expense_categories mapping for External ID [##]. |
Scenario | - |
Potential Cause | Vendor bills or expense reports syncing from NetSuite to Kantata have an expense category that is not mapped to an expense category in Kantata. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the [Expense Category] selected in NetSuite is correct
-or- If the [Expense Category] in NetSuite is incorrect
|
Exception (19) Maximum Characters Allowed for Company Name Field
Error Text | The field company name contained more than the maximum 830 characters allowed. |
Scenario | - |
Potential Cause |
The project's title in Kantata is longer than the allowed (83) characters in NetSuite. |
Resolution |
For resolution, complete the following process:
|
Exception (20) Incorrect Kantata Project ID
Error Text | NetSuite::Records::Job with OPTIONS={:internal_id=>"#####"} could not be found. |
Scenario | - |
Potential Cause |
The Kantata custom field designated to hold the NetSuite Project ID has the incorrect Project ID.
Note: Sometimes the Customer ID and the Project ID are mistakenly switched.
|
Resolution |
For resolution, complete the following process:
|
Exception (21) Subsidiaries Mapping Error for Kantata ID
Error Text | No subsidiaries mapping for Kantata ID [####]. |
Scenario | - |
Potential Cause | The Subsidiary custom field in Kantata is not mapped on the Subsidiary Mapping Table on the integration platform. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the Subsidiary Custom Field on the Kantata Project is correct:
-or- If the Subsidiary Custom Field on the Kantata Project is incorrect:
|
Exception (22) User Roles not Mapping for Kantata ID
Error Text | No user_roles mapping for Kantata ID [######]. |
Scenario | - |
Potential Cause | The role a user tracked time under is not mapped under the Sale Item Mapping Table. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the Role within Kantata is correct
-or- If the Role within Kantata is incorrect
|
Exception (23) Blank Category
Error Text | Category can't be blank. |
Scenario | - |
Potential Cause | Importing a vendor bill or expense report from NetSuite that doesn't have a category chosen on the line level of that transaction. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the Category of the NetSuite Transaction Line Syncs to Kantata
-or- If the Category of the NetSuite Transaction Line Doesn't Sync to Kantata
-or-
|
Exception (24) Missing Fields within Kantata Project
Error Text |
Please enter value(s) for: Client -or- Please enter value(s) for: Subsidiary |
Scenario | - |
Potential Cause | Creation of a new NetSuite project from Kantata if the Kantata project does not have the NetSuite Client ID or Subsidiary fields filled out. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the Project Doesn't Sync to NetSuite
-or- If the Project Syncs to NetSuite
|
Exception (25) NetSuite Missing Values: Time Entry, Expense Report, or Vendor Bill
Error Text |
Please enter value(s) for: Department, Location. -or- Please enter value(s) for: Class. |
Scenario | - |
Potential Cause | Creation of a time entry, expense report, or vendor bill in NetSuite when one or more of the above segments is a required field and is not set to match in NetSuite. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Verify Mapped Details on NetSuite Employee Record
Note: When creating Time Entires and Expense Reports in Netsuite the Department and Class default from the Employee Record.
Setting the Location and Department Segments as Not Required
Note: When creating vendor bills from Kantata to NetSuite the Location and Department are not populated by the integration. Those segments must be set as Not Required to sync successfully via the integration.
|
Exception (26) Time Tracked to Role not Mapped to Service Item
Error Text | You must enter a service item for this customer. |
Scenario | - |
Potential Cause | This NetSuite error occurs when time is tracked to a role in Kantata that is not mapped to a service item in NetSuite. |
Resolution |
For resolution, complete one of the following processes based on circumstance: If the Time Entry Role is Correct
-or- If the Time Entry Role is Incorrect
|
Exception (27) Negative Amount within Vendor Bill or Expense Report
Error Text | Amount must be between 0 and 1,000,000,000,000 cents. |
Scenario | - |
Potential Cause | This NetSuite error occurs when there is a line on the Vendor Bill of Expense Report that is negative or over 1 trillion dollars. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance:
Note: Core Kantata doesn't fully support negative values for expenses.
|
Exception (28) Duplicate Employee Added to Same Project
Error Text | Net/Role must be unique. |
Scenario | - |
Potential Cause |
This NetSuite error occurs when the same employee in NetSuite is being added to the same project twice. -and/or- This error most often occurs when 2 different users in Kantata are mapped to the same employee in NetSuite on the User Mapping Table. |
Resolution |
For resolution, complete the following process: Review and Manage Users
|
Exception (29) Billable Time Tracked to Non-Billable Task
Error Text | You do not have permissions to set a value for element isbillable 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. |
Scenario | - |
Potential Cause |
Billable time in Kantata is tracked to a task marked as Non-Billable in NetSuite. -or- Billable time is being tracked to a NetSuite project that has no Customer. -or- When syncing expenses if the expense category is not mapped in the mapping tables. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: If the NetSuite Project has no Customer
Note: In this case, the customer can't be added via the integration after the project has been created in NetSuite.
If the Task is Billable Instead of Non-Billable
If the Time Entry is Non-Billable Instead of Billable
|
Exception (30) User Time Entries not Syncing to Project
Error Text | Resources for time and material projects must be in the customer's subsidiary. The following resources are in a different subsidiary: [Employee Names]. |
Scenario | - |
Potential Cause |
Time entries of a Kantata user are syncing to a project in NetSuite that is not the same subsidiary listed as the NetSuite employee.
Note: An employee must be in the same subsidiary as the NetSuite project to submit time entries to said NetSuite project unless the Intercompany Time and Expense feature is enabled.
|
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: If the Employee Subsidiary Must Change in NetSuite
If the Project Subsidiary Must Change - Kantata Originating System
-or- If the Project Subsidiary Must Change - NetSuite Originating System
|
Exception (31) NetSuite Task Can't Track Employee Time
Error Text | Invalid casetaskevent reference key [###] for customer [#####]. |
Scenario | - |
Potential Cause | This NetSuite error occurs when a task in NetSuite is not able to have an employee's time tracked to it.
Examples:
|
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: If the Task Status is Completed
Warning: If the Task Status is Completed in NetSuite, NetSuite will not allow the employee time to be tracked on that task.
If the Employee is not Assigned to the Task in NetSuite
Warning: If the Employee is not assigned in NetSuite, NetSuite will not allow the employee time to be tracked on that task.
|
Exception (32) Invalid Company Reference Key
Error Text | Invalid company reference key [####]. |
Scenario |
|
Potential Cause | The project within NetSuite has been marked Inactive. This means that no updates can be made. |
Resolution |
For resolution, you may need to complete one or all of the following processes based on circumstance: Mark the Project as Active If the task needs to be synced, the project must be marked as Active.
-or- Dismiss the Event
|
Exception (33) Key Information Missing
Error Text | An unexpected error occurred. Error ID: ke4b12iwdqfylby9ye6i. |
Scenario |
|
Potential Cause | Some key information is missing or incorrect in the payload for the invoice. |
Resolution |
For resolution, complete the following process: Verify and Update Information in NetSuite
|
Exception (34) Multi-Currency Feature
Error Text | NetSuite::Records::Currency with OPTIONS={:internal_id=>nil} could not be found. |
Scenario |
|
Potential Cause | The Multi-Currency Feature is not turned on in NetSuite. |
Resolution |
For resolution, complete the following process: Verify and Turn On the Multi-Currency Feature
|
Exception (35) Planned Work Feature
Error Text | Please enter value(s) for: Planned Work. |
Scenario |
|
Potential Cause | The client has enabled the Planned Work feature in NetSuite. |
Resolution |
For resolution, complete the following process: Disable the Planned Work Feature
|
Exception (36) Invalid Item Reference Key for Subsidiary
Error Text | Invalid item reference key [####] for Subsidiary [####]. |
Scenario |
|
Potential Cause |
This is likely a problem with the item in the Sale Item Mapping Table. The item that the integration is trying to add to the time entry when it's creating the record is not allowed in the subsidiary that the project—or employee—is in. -or- The Time Entry line item needs to be mapped to a Service for Sale. NetSuite items that are labeled as Service for Purchase are unable to be used in this case. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance:
|
Exception (37) User Email Address is Associated to a Different Account
Error Text | {"errors"=>[{"type"=>"system", "message"=>"Not found"}]}. |
Scenario |
|
Potential Cause |
The user's email address is associated with a different Kantata account. The scenario will not move users from a different Kantata account to yours. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance: If the User Needs to be Added to the Kantata Account
If the User was Removed from the Kantata Account
-or-
If the User Needs to be Verified in a Kantata Account History
|
Exception (38) Exception Stuck in the Created Status
Error Text | Event is stuck in created status. |
Scenario |
|
Potential Cause |
There is a paid invoice associated with the event within NetSuite, but no Kantata Invoice ID is associated with it. The event is created but it should not be.
Note: As of July 7, 2021, this is expected to be resolved at a future date.
|
Resolution |
For resolution, complete the following items:
|
Exception (39) Invalid Category Reference Key for Subsidiary
Error Text | Invalid category reference key 8 for subsidiary 1. |
Scenario |
|
Potential Cause |
Expense category mappings are not matched one to one, and the integration is unable to determine which mapping to use when sending data from Kantata to NetSuite. |
Resolution |
For resolution, complete the following items:
|
Exception (40) Must Enter Service Item for Customer
Error Text | You must enter a service item for this customer. |
Scenario |
|
Potential Cause |
At the time the user entered their timesheet, they didn't have a Default Role. This means that no Role was defined at the project level. This causes the role_id to be null. This can also be seen in the Payload for the event. |
Resolution |
For resolution, complete the following process: Edit the Time Entry Role for the Time Entry
|
Exception (41) Must Enter Service Item for Customer
Error Text | You do not have permissions to set a value for element currency 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. |
Scenario |
|
Potential Cause |
The Kantata project currency has been changed after syncing to NetSuite or otherwise does not match the NetSuite project’s currency. |
Resolution |
For resolution, you may need to complete one or all of the following items based on circumstance: If the Kantata Project Currency is Incorrect
-or-
|
Comments
0 comments
Please sign in to leave a comment.