Skip to main content

QuickBooks Desktop Troubleshooting

Diagnose and resolve common issues with the QuickBooks Desktop integration.

Queue Management​

Monitor sync status from the QuickBooks Desktop Queue page.

Accessing the Queue​

  1. Go to Settings > Integrations
  2. Click Queue next to QuickBooks Desktop

Queue Status Indicators​

StatusMeaning
QueuedWaiting for Web Connector to process
In ProgressCurrently being processed
CompleteSuccessfully processed
ErrorFailed—check error message for details

Error Handling​

Edit Sequence Mismatch (Error 3200)​

What it means: The record was modified in QuickBooks after Readybuild queued the sync.

How it's handled: The system automatically:

  1. Extracts the new Edit Sequence from the error response
  2. Updates the stored Edit Sequence
  3. Retries the operation with the correct sequence

If it persists: The record may be getting modified frequently in both systems. Consider syncing less frequently or coordinating changes.

Reference Not Found (Error 3180)​

What it means: A referenced entity (like a customer or vendor) doesn't exist in QuickBooks.

How it's handled:

  1. The system logs the error with full details
  2. The item is removed from the sync queue to prevent repeated failures
  3. Review the log to identify the missing reference

Resolution:

  1. Check if the referenced entity was deleted in QuickBooks
  2. Re-sync the parent entity first (e.g., sync customer before invoice)
  3. Verify the entity exists in QuickBooks

Status Tracking​

The integration tracks sync status for each entity using AccountingIntegrationStatus:

StatusDescription
PendingQueued for sync
SyncedSuccessfully synced
ErrorSync failed
SkippedIntentionally not synced

Common Issues​

Web Connector Not Syncing​

Problem: Data isn't syncing between systems.

Solutions:

  1. Verify Web Connector is running (check system tray)
  2. Ensure QuickBooks is open and logged in
  3. Check that "Readybuild Integration" is checked in Web Connector
  4. Verify the password (Access Code) is correct
  5. Click Update Selected to force a sync

"Application Not Found" Error​

Problem: Web Connector can't find QuickBooks.

Solutions:

  1. Open QuickBooks Desktop and log into your company file
  2. Close and reopen Web Connector
  3. Try syncing again

Access Code Changed​

Problem: Sync fails after system update or security change.

Solutions:

  1. Go to Settings > Integrations > QuickBooks Desktop in Readybuild
  2. Copy the current Access Code
  3. Update the password in Web Connector

Queue Items Stuck​

Problem: Items remain in "Queued" status indefinitely.

Solutions:

  1. Verify Web Connector is running
  2. Check that auto-run is enabled or manually click Update Selected
  3. Review QuickBooks for any prompts or dialogs blocking the sync
  4. Check if QuickBooks is in single-user mode (multi-user issues)

Employees Not Appearing​

Problem: New employees don't show in the mapping dropdown.

Solutions:

  1. Click the Refresh button on the Employee Mapping tab
  2. Run a Web Connector sync
  3. Wait for the sync to complete (check the queue)
  4. Refresh the Readybuild page

Time Entries Not Exporting​

Problem: Approved time entries aren't appearing in QuickBooks.

Solutions:

  1. Verify the employee has a mapping configured
  2. Check that a default payroll item is set
  3. Ensure the time entry is in "Approved" status
  4. Review the queue for error messages

Invoice Line Items Missing Cost Codes​

Problem: Invoice exports fail or have incorrect item references.

Solutions:

  1. Configure default cost code mappings for all item types
  2. Verify the QuickBooks service items exist
  3. Check for category-specific overrides that may be missing

Frequently Asked Questions​

Q: Can I use QuickBooks Desktop and QuickBooks Online at the same time?

A: No, only one QuickBooks integration can be active. Choose the version that matches your accounting software.

Q: Does the Web Connector need to run all the time?

A: We recommend keeping the Web Connector running continuously during business hours and setting the auto-run interval to the shortest setting possible for the best experience.

Q: What happens if QuickBooks is closed during a sync?

A: The Web Connector will fail and retry on the next scheduled sync. No data is lost.

Q: How do I sync time entries to QuickBooks?

A: Time entries are exported when they're approved in Readybuild. The export uses the employee and payroll mappings you've configured.

Q: Can I map one Readybuild user to multiple QuickBooks employees?

A: No, each Readybuild user maps to one QuickBooks employee. Use separate Readybuild accounts for employees who need distinct QuickBooks mappings.

Q: How do customer payments sync from QuickBooks?

A: Payments recorded in QuickBooks are imported into Readybuild automatically. The system matches payments to invoices using the QuickBooks transaction ID and applies them accordingly.

Q: How do bills sync between systems?

A: Bills are bidirectional. Bills created in Readybuild export to QuickBooks, and bills created in QuickBooks import to Readybuild. The bill is matched to a project based on the Job/Customer reference in the line items.

Q: If I update a customer in QuickBooks, does it update in Readybuild?

A: No. Customer, vendor, and project data flows from Readybuild to QuickBooks only. Changes made in QuickBooks are not automatically synced back. Bills and payments are the exception—those do import from QuickBooks into Readybuild.

Q: How are large datasets handled?

A: The integration uses QuickBooks' iterator functionality to process records in batches (typically 100 at a time), preventing timeouts and memory issues.

Q: Can I sync purchase orders to QuickBooks?

A: Yes, purchase orders created in Readybuild are exported to QuickBooks with full line item details, vendor references, and project associations.

Q: How does job costing work with the integration?

A: Projects in Readybuild are synced as Jobs in QuickBooks, linked to their parent customer. All related transactions (invoices, bills, payments) maintain these project references for accurate job profitability reporting.

Getting Help​

If you encounter issues not covered here:

  1. Check the queue for specific error messages
  2. Review the QuickBooks Desktop logs (if available)
  3. Verify Web Connector is on the latest version
  4. Contact Readybuild support with:
    • Queue item ID (if applicable)
    • Error message text
    • Steps to reproduce the issue