Skip to main content

Troubleshooting

Required Permission
Company Setup - You must have the Company Setup 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

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.

Are historical records synced?​

Only records created or modified after the integration is set up will sync automatically. Use Link Entities to connect historical records.

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.

Can I undo a sync?​

Individual sync operations cannot be undone. To remove synced data, you must delete or modify records in both systems manually.

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