Skip to content
English
Customer portal Sign in
Go to Tai Software
  • There are no suggestions because the search field is empty.

QuickBooks Sync – Troubleshooting Guide

This guide will help you identify and resolve common QuickBooks sync errors within the TMS. You’ll learn how to spot transactions that failed to sync and the best steps to troubleshoot them.

Before You Begin

Every time you attempt to sync a payable from the Accounting Sync page, the system provides two clear indicators to confirm whether the transaction synced successfully to QuickBooks:

  1. Green “Sync Completed” Message: Appears on the upper right-hand side of the page after a successful sync.

  2. Blue Loading Bar: The color of the synced payable remains blue, indicating the transaction was successfully shared with QuickBooks.

Tip: If either of these indicators does not appear as expected, the transaction may have encountered a sync issue.

The example below demonstrates a properly completed sync:


Handling Sync Errors

If you see a red loading bar or receive an error message during a QuickBooks sync, this indicates that the transaction failed to sync.

To troubleshoot:

  1. Go to the Shipment Activity Log for the shipment associated with the failed transaction.

  2. Review the detailed error message logged by the system. This will show the exact issue returned by QuickBooks, helping you identify why the sync failed.

Tip: Checking the Activity Log first ensures you have the full error details before taking corrective action, whether that’s fixing missing data, updating account mappings, or retrying the sync.

 Sync Workflow: Ideal Order 

⚠️ Important: Always sync in the following order to avoid reconciliation issues in QuickBooks:

  1. Sync Invoices
  2. Sync Bills
  3. Sync Invoice Payments
  4. Sync Bill Payments

Using Sync All is not recommended. Since all transaction types sync simultaneously, invoice and bill payments may process before their associated invoices and bills are created in QuickBooks. This will result in unlinked payments that require manual reconciliation in QuickBooks.

Common QuickBooks Sync Errors and How to Resolve Them


Invoicing:

1. Failed to Sync Invoice. Error: Customer Sync Error. Error: BadRequest. Details: The name supplied already exists. : null ,

This error occurs when there's any additional space within the customer name in the TMS that doesn't match the same spacing that has the customer name in QuickBooks.

To fix it, go to the customer profile under your organization, click on Edit record, and confirm that there are no additional blank spaces within the customer name. Please make sure it matches the QuickBooks wording/spacing and save it. After that, the invoice should be synced with no problem.

 

2.  Failed to Sync Invoice 'XXXXXXXXX'. Error: Invoice number 'XXXXXXXXX' exceeds QuickBooks 21-character DocNumber limit (length 23).

This error is specifically related to the invoice number and the number of characters that were used when updating the invoice number after it was created. Just so you know, the system will automatically assign the shipment ID as the invoice#; however, in scenarios where you need to change the invoice number for internal purposes and management, make sure that the new invoice number is between 0 and 21 characters, including digits/special characters, and blank spaces.

Once you ensure the invoice number is under the 21-character limitation, proceed to sync it over.

 

3. Failed to Sync Invoice. Error: Sync Failure: BadRequest. Details: Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=119843004 is assigned to TxnType=Invoice with TxnId=15917

This happens when the user tries to sync an invoice that was previously synced to that QuickBooks account with the same invoice number. Usually, this occurs when you initially sync an invoice and then proceed to delete it to make any changes within the load pricing. If the invoice does not get deleted from your QuickBooks account prior to making the changes in the TMS, the system will determine that there's already a payable under that customer profile using the same invoice number, and it will mark it as a duplicate, causing the error.

The easy fix is to go to your QuickBooks account using the following link: https://qbo.intuit.com/app/invoice?txnId=xxxxx 

Please make sure to replace the xxxx from the URL with the TxnId that you got from the error within the shipment activity log. In this specific shipment example, the URL would look like this after you replace the TxnID: https://qbo.intuit.com/app/invoice?txnId=15917

Once you open the link, QuickBooks should redirect you to the existing invoice that was previously synced; you will have to delete it from there. After that, you can go back to the TMS and sync the invoice from scratch without having any issues.

4. Failed to Sync Invoice xxxxxxxxx. Error: Sale Account 'TRANS' is not set up as an active Product/Service in QuickBooks.



This error occurs when the account code used for the invoice does not exist as an active Product or Service in QuickBooks. Go to QuickBooks Online > Products and Services, find the item matching the account code name and confirm it is active. If it does not exist, create a new Service with that exact name and mark it as active. Once done, re-sync the invoice.

Bills:

1. Failed to sync Bill .  Error: Sync Failure: BadRequest. Details: The account period has closed and the account books cannot be updated through through the QBO Services API. Please use the QBO website to make these changes. , .

This error is displayed after the user tries to sync any transaction to QuickBooks when the accounting period has ended on your books, and the QuickBooks setup requires you to go to the account settings and update the closing date of the books. The path to change this configuration is the following: Account settings> Advanced> Accounting, and update the closing date:

 

2.  Failed to sync Bill XXXXXXXXX. Error: Bill number XXXXXXXXX exceeds QuickBooks 21-character DocNumber limit (length 23) 

When syncing Bills, you might have the same inconvenience as we already mentioned with the Invoice numbers; the Bill number cannot have more than 21 characters in total, considering the blank spaces/digits, and special characters. You must update the bill number and resync this payable to fix the error.

 

3. Failed to sync Bill 112885927.  Error: The 'Accounts Payable' Account was not found in the QuickBooks Chart of Accounts.

After that, select the account name and type, and proceed to save it; it should look like this:

Once you add this account payable to your chart of accounts, the system should allow the bill to sync with no issues.

 

4. Failed to sync Bill xxxxxxx.  Error: Sync Failure: BadRequest. Details: Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=xxxxxxis assigned to TxnType=Bill with TxnId=xxxxxx, .

This error appears when you try to sync a new carrier bill over to QuickBooks, but there's already a bill in QuickBooks with that specific bill number. For that reason, the system will take it as a duplicate and prevent the user from syncing it again until the Bill# gets changed or you delete the duplicate in QuickBooks. 

The same way the system verifies if an invoice transaction already exists in QuickBooks with the same number, it applies the same logic for the vendor Bills. 

https://qbo.intuit.com/app/bill?&txnId=xxxxx

Please make sure to replace the xxxx from the URL with the TxnId that you got from the error within the activity log. Once you access that link, QuickBooks will redirect you to the page of the bill that is already associated with the bill number you tried to sync. The majority of the time, it's an old bill with outdated information, or a duplicate that was previously synced from the TMS but never deleted from QuickBooks.

5. Failed to sync Bill XXXXXXXXX. Error: Cost Account 'XXXX' was not found in the QuickBooks Chart of Accounts. Add or activate an Account with this exact name.



This error occurs when the cost account mapped to the bill line items does not exist or has been made inactive in QuickBooks. Go to QuickBooks Online > Chart of Accounts, find the account matching the exact name shown in the error and confirm it is active. If it does not exist, create a new account with that exact name. Once done, re-sync the bill.

Invoice Payments:

⚠️ Note: If an invoice payment is synced before its associated invoice has been synced to QuickBooks, the system will not fail. Instead, the payment will be created in QuickBooks as unapplied and the following warnings will appear in the Shipment Activity Log:

  • "Payment ID:XXXXXXX warning: Payment submitted as unapplied (no invoice linkage). Could not match invoice numbers in QuickBooks: [Invoice Number]."
  • "Payment ID:XXXXXXX warning: Invoice XXXXXXXXX was not found in QuickBooks. Payment was applied, but it will not be linked to this invoice."

To resolve this, sync the invoice first. However, please note that syncing the invoice after the payment has already been submitted will not automatically link them in QuickBooks — a manual adjustment in QuickBooks will be required to associate the payment with the invoice.

1. Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:The number is not within supported range. Min:0 Max:999,999,999 supported. Supplied value:-90.

This error usually appears when the payable contains negative amounts, even though that is not that common. The solution to this problem is to confirm the total amount for the invoice and make sure that the invoice payment was registered for a positive amount.

 

2. Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:Business Validation Error: You cannot enter more than 21 characters in the doc_num field. You tried entering ch_3PbCeXR..., which is 27 characters..

For this type of error, the resolution is pretty easy, just as the same issue we already checked with the invoice number, QuickBooks does have certain criteria that need to be met when they receive an invoice payment, the issue occurs when any of the fields such as Check Memo, Check reference number, etc has more than 21 characters. To fix it, just go to the payment and change the reference numbers to a different number with fewer characters.

 

3. Failed to sync Invoice Payment. Error: 'Accounts Receivable' account was not found in Quickbooks.

This issue relates to the bank accounts you have registered under your QuickBooks account. It fails if the Accounts Receivable type of account was not previously created and saved. To fix it, please go to QuickBooks, click on CHART OF ACCOUNTS> NEW, and add a new account with the name " Accounts Receivable" and Account Type: "Accounts Receivable (A/R)".

It should look like this:

Once it gets saved, you can go ahead and sync the invoice payment with no issues.

 

4.Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:Object Not Found : TxnType does not match read: Credit Memo expected: Invoice.

For this type of issue, you need to go to the invoice payment you are trying to sync and ensure that there are no shipments with a total invoice amount of $0. If so, QuickBooks will reject the sync because a payment for a total of $0 is not acceptable on their end. 

If the invoice payment contains multiple shipment invoices, please go to the invoice payment and remove the invoices with a total amount of $0 or adjust the pricing to match the real amount. After that, you should be able to sync the payment.

 

5. Warning: Failed to sync Invoice Payment. Warning: Invoice XXXXXXXXX was not found in QuickBooks by number (cached QB reference 'XXXXXXXXX' is stale or invalid). Payment was applied, but it will not be linked to this invoice.


This warning appears when an invoice was previously synced to QuickBooks but was later deleted from QuickBooks. The payment will still sync successfully, but it will not be linked to the invoice. To resolve this, delete the invoice payment in TMS, re-sync the invoice to QuickBooks first, then re-register and re-sync the payment.

Bill Payments:

When syncing Bill payments, there will always be certain errors that have the same troubleshooting for us to confirm what's the root cause of the issue; the majority of the time is due to missing bills (Not previously synced, deleted, or modified) in QuickBooks. 

1. Failed to Sync Bill Payment (ID: xxxxxx) Error: Sync Failure: Validation Exception was thrown.Details:Object Not Found : Something you're trying to use has been made inactive. Check the fields with accounts, customers, items, vendors or employees..

To fix this, you will have to havo to go to the QuickBooks account and confirm that the bank account/ vendor profile is currently active; if by any chance any of those have been set to inactive, no transactions are going to be located and stored successfully. 

2. Failed to Sync Bill Payment (ID: xxxxxxx). Error: Unable to sync Bill Payments. A General Ledger of Bank Type must be set up for this accounting organization.

This error occurs when no bank-type GL account has been configured for this organization. Go to Accounting Sync > GL Accounts and set up an account of type "Bank" before attempting to sync bill payments again.

The activity log will look like this:

 

3. Failed to Sync Bill Payment. Error: Bank account 'Account Name' (expected Bank type) not found in QuickBooks.

This error occurs when the bank account configured in TMS does not exist in QuickBooks with the exact same name and Bank account type. Go to QuickBooks > Chart of Accounts and confirm the account exists with the exact name and is set to type "Bank."

The activity log will look like this:

 

3. 1 Failed to Sync Bill Payment. Error: Bank account 'Account Name' (expected Credit Card type) not found in QuickBooks. 

Same as above but for credit card payments. Confirm the account exists in QuickBooks Chart of Accounts with the exact name and type "Credit Card."

The activity log will look like this:

4. Failed to Sync Bill Payment (ID: 1524737) Error: Sync Failure: Validation Exception was thrown.Details:Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=11138133475 is assigned to TxnType=Check with TxnId=19125.

To fix this issue, you just have to change the CHECK REF#  that was used to register the Bill payment in the TMS. If QuickBooks recognizes another bill payment with the same number already registered under your account, it will take it as a duplicate. 

If you need to confirm which bill payment under your QuickBooks account currently has that same CHECK REF#, use the TxnID from the error the system stored within the shipment activity log and replace the XXX in the following URL: https://qbo.intuit.com/app/billpayment?&txnId=XXX.

Once you do so, you can use that link to be redirected to the payment stored in your QuickBooks account.

 

⚠️ Note: If a bill payment is synced before its associated bill has been synced to QuickBooks, the system will not fail. Instead, the payment will be created in QuickBooks as a Check and the following warnings will appear in the Shipment Activity Log:

  • "Payment ID:XXXXXXX warning: Bill payment submitted as a Purchase (no bill linkage). Could not match bills in QuickBooks: [Bill Number]."
  • "Payment ID:XXXXXXX warning: Bill XXXXXXX was not found in QuickBooks. Payment was applied, but it will not be linked to this bill."

The activity log will look like this:

To resolve this, sync the bill first. However, please note that syncing the bill after the payment has already been submitted will not automatically link them in QuickBooks — a manual adjustment in QuickBooks will be required to associate the payment with the bill.

 

5.Failed to Sync Bill Payment (ID: XXXXXX). Error: Cost Account 'Freight COS' was not found in the QuickBooks Chart of Accounts. Add or activate an Account with this exact name 

This occurs when a bill payment is synced before the bill exists in QuickBooks and the Freight COS cost account is inactive or missing in QuickBooks. Go to QuickBooks → Chart of Accounts → find Freight COS → make it active. Then re-sync the bill payment from the failed queue in TMS.

The activity log will look like this: