Skip to main content

Troubleshooting

Required Permission
Manage Company Settings - You must have the Manage Company Settings permission to access this setting.

This page covers common issues with the QuickBooks Online integration and how to resolve them.

Connection Issues​

"Failed to connect to QuickBooks"​

Possible causes:

  • Popup blocker prevented the OAuth window from opening
  • QuickBooks session expired during authorization
  • Insufficient permissions in QuickBooks

Solution:

  1. Check that pop-ups are allowed in your browser for Readybuild
  2. Ensure you're signing into the correct QuickBooks account
  3. Verify you have admin access to the QuickBooks company
  4. Try disconnecting and reconnecting

Authorization Expired​

Problem: "Authorization expired" error appears in integration settings

Solution:

  1. Go to Settings > Integrations > QuickBooks Online
  2. Click Disconnect
  3. Click Connect QuickBooks Online to re-authorize
  4. Complete the OAuth flow to refresh your connection

Sync Issues​

Records Not Syncing​

Problem: Records not appearing in QuickBooks after saving in Readybuild

Check these items:

  1. Is the record linked? Verify the record has a QuickBooks connection in Entity Linking
  2. Are required fields populated? Name, email, and other required fields must not be empty
  3. Check sync status: Look for error indicators on the record
  4. Verify QuickBooks subscription: Ensure your QuickBooks account is active

Invoices Not Syncing​

Problem: Client invoices aren't appearing in QuickBooks

Solution:

  1. Verify the invoice has sendToAccounting enabled
  2. Confirm the project is already synced to QuickBooks
  3. Check that the project's contact is synced as a Customer

Time Entries Not Syncing​

Problem: Time entries don't appear in QuickBooks as Time Activities

Solution:

  1. Time entries must be locked/approved before syncing
  2. Each employee needs their QuickBooks Online Employee ID configured in team member settings
  3. Sync is manual - use the time approval interface to trigger sync

Field Receipts Not Syncing​

Problem: Field expenses don't appear as Purchases in QuickBooks

Solution:

  1. Field expense must be in Approved or Paid status
  2. The vendor must be synced to QuickBooks first
  3. Cost codes must have QuickBooks account mappings configured
  4. Verify the Default Payment Account is set in Configuration

Duplicate Records​

Same Contact Appears Twice in QuickBooks​

Problem: Same contact appears as two separate Customers in QuickBooks

Causes:

  • Record was created in both systems before linking
  • Link Entities was not used before initial sync

Solution:

  1. In QuickBooks, merge the duplicate customers
  2. In Readybuild, go to Link Entities
  3. Find the contact and click Link
  4. Select the merged customer from QuickBooks
  5. Confirm the link

Preventing Future Duplicates​

  1. Use Link Entities to connect all existing records before relying on automatic sync
  2. Check for existing records in both systems before creating new ones
  3. Establish a process for which system is the "source of truth" for new records

Common Error Messages​

"Project not synced"​

Meaning: Attempting to sync an invoice or payment for a project that hasn't been synced to QuickBooks yet

Solution: Sync the project first, then retry the invoice/payment sync

"Missing employee QB ID"​

Meaning: Time entry sync failed because the employee doesn't have a QuickBooks Employee ID configured

Solution: Go to team member settings and configure the QuickBooks Online Employee ID for that employee

"Vendor not synced"​

Meaning: Attempting to sync a field expense for a vendor that hasn't been synced to QuickBooks

Solution: Sync the vendor first, then retry the field expense sync

"Missing sendToAccounting flag"​

Meaning: Invoice, payment, or credit memo doesn't have the accounting sync flag enabled

Solution: Enable the sendToAccounting option on the record before it will sync

"QuickBooks permanently rejected this record"​

Meaning: QuickBooks refused the record's content rather than failing temporarily — most often a name it won't accept. Retrying sends exactly the same thing, so Readybuild stops retrying instead of attempting it every hour indefinitely.

Most common cause: a project or contact name containing a colon (:). QuickBooks reserves the colon to separate a customer from its sub-jobs, so it can't appear in a name.

Solution:

  1. Open the record in Readybuild and edit the name — remove any colon, and shorten a very long name
  2. Save. The edit queues a fresh sync automatically
  3. Confirm the record now appears in QuickBooks

If the name looks fine and it still won't sync, check the record's error details (below) for the message QuickBooks returned.

Sync Status Indicators​

StatusIndicatorWhat It Means
PendingGray clockQueued for sync, will process soon
SyncedGreen checkmarkSuccessfully synchronized
ErrorRed warningSync failed - hover for details
SkippedGray dashRecord not eligible for sync

Viewing Error Details​

When a record shows an Error status:

  1. Hover over the error indicator
  2. A tooltip displays the specific error message
  3. Address the issue described in the message
  4. The record will retry on the next sync cycle

Frequently Asked Questions​

Can I connect multiple QuickBooks companies?​

No, Readybuild connects to one QuickBooks Online company at a time. To switch companies, disconnect the current one and connect to the new one.

What happens if I delete a record in QuickBooks?​

The linked record in Readybuild is not automatically deleted. You'll need to unlink and delete it manually if desired.

What happens if I delete a Client Invoice, Payment, or Credit Memo in Readybuild?​

Deleting a Client Invoice, Payment, or Credit Memo in Readybuild propagates the deletion to QuickBooks Online — the corresponding QuickBooks Invoice, Payment, or Credit Memo is deleted as part of the same action.

Restoring does not restore the QuickBooks object

These records are soft-deleted in Readybuild and can be restored from the Change Log. However, QuickBooks Online deletions are permanent — restoring the record in Readybuild does not recreate the QuickBooks object. The restored record comes back unlinked from QuickBooks and can be re-synced from its QuickBooks Status chip.

Are historical records synced?​

Only records created or modified after the integration is set up will sync automatically. Use Match & Link to connect historical records in bulk, or Entity Linking to connect them one at a time.

Why is the Run button disabled in Match & Link?​

Two things disable it. Either the entity's sync direction is not set to Disabled — change it under Settings > Integrations > QuickBooks Online > Sync Direction — or an earlier step it depends on hasn't been completed yet. The step shows a warning naming which one applies. See Match & Link for the full dependency list.

Match & Link says a run is already in progress​

Only one run can be active per company. On Bills and Invoices this includes the payment phase that follows the main run, so wait until the Processing payments bar finishes before starting the next step. Reload the page if you're unsure — an in-progress run reappears with its live progress.

Why did a record come back as Pending instead of linking?​

Match & Link links a record only when it finds exactly one candidate. The reason column tells you which case you hit: no candidate was found, or several were found and the reason ends requires manual selection. Either way, click Link on the row and pick the right record yourself. Match & Link never chooses between two possible matches on its own.

Can I sync custom fields?​

Standard field mapping is predefined. Custom field sync is not currently supported.

How do I know if sync is working?​

Check the "Last Sync" column in the Link Entities view. Recent timestamps indicate active sync.

Why did my bill sync create a duplicate payment?​

If a bill was already paid in QuickBooks before linking, syncing the Readybuild bill payment may create a duplicate. Always reconcile payment status before linking existing bills.

Someone converted a sub-customer to a QuickBooks Project — what changes?​

The entity link stays intact and transactions continue to sync correctly. After conversion, Readybuild stops pushing project-level updates (title, site address, description) — those can be edited directly on the QuickBooks Project. See Sub-Customer to Project Conversion for the full breakdown.

Can I undo a sync?​

Individual sync operations cannot be undone. For most entity types, to remove synced data you must delete or modify records in both systems manually.

The exception is Client Invoices, Payments, and Credit Memos: deleting one of these in Readybuild also deletes the linked QuickBooks Online object automatically, so you do not need to delete it separately in QuickBooks. This propagation is permanent — restoring the record in Readybuild brings it back unlinked from QuickBooks and does not recreate the QuickBooks object.

Getting Additional Help​

If you continue to experience issues:

  1. Check sync logs: Review the sync status and error messages on affected records
  2. Verify configuration: Ensure all default settings are properly configured
  3. Re-link entities: Sometimes unlinking and re-linking a record resolves sync issues
  4. Contact support: Provide specific error messages and affected record IDs when reaching out