Minimum Version Required: 26.01
Pre-Conditions
The system must be actively using the Encompass QuickBooks integration.
The user must have adequate permissions to view the Encompass sync dashboard and the relevant Accounts/AP Accounts tables.
The user must have access to the QuickBooks company file to verify existing accounts and vendors.
Steps
Identify the unmatched element: Locate the element ID in the error heading (e.g., "Error Code: 2500 Invalid Reference ID: Names element id XX not found"). Match that ID to the element (AP Account, Account, etc.) to determine which record in Encompass could not be matched.
Filter and confirm the record in Encompass: If the unmatched element is an AP Account, take the element ID and filter on the List ID in the AP Accounts table to confirm the Vendor that could not be found in Quickbooks. Repeat this process for Accounts or any other specific element.
Verify the entity in QuickBooks: Check if the Vendor or Account listed does exist in QuickBooks. If it does exist, this means Encompass has already matched the QuickBooks Account with a different Encompass Account.
Correct mismatched data: Check similarly named Accounts in Encompass and clear the ListID field if this is a mismatch.
Create missing entities: If the Account listed does not exist in QuickBooks, create the Account in QuickBooks.
Contact Support: If the issue persists after following these steps, please contact Encompass support for further assistance. To ensure efficient troubleshooting, gather and provide the following information:
Exact error messages or codes encountered (including the specific Element ID).
Screenshots or video recordings of the issue.
Log files or the specific Exchange Task ID.
The exact steps taken by the customer that led to the issue.
The date and time the issue was first observed and any recurrence.
Any changes made to the system before the issue appeared.
Fields And Definitions
Error Code 2500: Indicates an invalid object reference or missing linked entity in the QuickBooks context. This message appears when Encompass cannot find a Vendor or Account in QuickBooks.
Element ID: The unique identifier found in the error heading used to map the error to the specific record in Encompass.
ListID: The cross-reference field in Encompass tables (like AP Accounts or Accounts) used to link the Encompass record directly to the QuickBooks entity.
Best Practices
Audit External Entities: Ensure that the target Customer, Vendor, Account, or Item entity is actively found in the external ledger.
Prevent Soft Deletions: Ensure the target entity has not been marked inactive or soft-deleted inside QuickBooks.
Maintain Accurate Mappings: Regularly monitor sync dashboards to prevent stale or corrupted external ID cross-reference mapping stored locally.
Respect Sync Order: Verify that payload operational order dependencies are satisfied before issuing the sync call.