Common Errors

1.1 "Cannot find Default Credentials"

Where it appears: QB_Auth__e platform event (Is_Success__c = false), displayed in the QuickBooks Connect UI.

Cause: The Quickbooks_Credentials__c protected custom setting does not have a record named Default. This record is created automatically by PostInstallScript on fresh install but may be missing in orgs that had the package manually set up or had their custom settings wiped.

Fix:

1. Go to Setup → Custom Settings → Quickbooks Credentials → Manage.

2. Verify that a record named Default exists with Client_ID__c, Client_Secret__c, and State_URL__c populated.

3. If missing, re-run PostInstallScript.createDefaultCredentials() in Anonymous Apex, or manually insert the record.

1.2 "Response not found" / "RESPONSE NOT FOUND" on QB records

Where it appears: Status_Description__c on Quickbooks_Customer__c, Quickbooks_Invoice__c, etc.

Cause: The QBO API call returned a response but the connector could not parse a valid entity from it. This usually means the QBO API returned an error body (Fault) instead of the expected entity JSON, or the network call failed silently.

Fix:

1. Check the Status_Description__c field for the raw error message appended by the batch class (e.g., BatchSFQBCustomerSync.execute RESPONSE NOT FOUND).

2. Open Setup → Apex Jobs and locate the relevant batch (BatchSFQBCustomerSync, BatchSFQBInvoiceSync, etc.) to check for apex exceptions in the debug log.

3. Retry the sync manually via the QuickBooks UI button on the record after resolving the underlying cause.

1.3 DefaultCompanyId showing "test"

Where it appears: All sync batch classes check CMQBConnectorUtility.getDefaultCompanyId(). If this returns "test", company assignment is skipped.

Cause: No QBO company has been connected yet, or the DefaultCompanyId and DefaultCompanyRecordId settings in Quickbooks_Common_Settings__c were not updated after authorization.

Fix:

1. Go to Admin Setup in the QuickBooks app and complete the authorization flow. After successful authorization, QBAuthController automatically sets DefaultCompanyId and DefaultCompanyRecordId.

2. Verify the values: Setup → Custom Settings → Quickbooks Common Settings → Manage → look for DefaultCompanyId (should be the QBO realmId, not "test") and DefaultCompanyRecordId (should be the Salesforce record ID of the Quickbooks_Company__c record).

1.4 "No Mapping found for this object" / "Mapping not found"

Where it appears: CMQBConnectorUtility.getFieldMappings() — surfaced in the QuickBooks UI when trying to sync a record.

Cause: No Custom_Field_Mapping__c record exists for this Salesforce object + company combination.

Fix:

1. Open the Admin Setup tab → Field Mapping section.

2. Ensure a mapping is configured for the relevant object (e.g., Account, Opportunity, Contact) and the correct Quickbooks Company.

3. If you recently added a new company, field mappings must be set up separately for each Quickbooks_Company__c record.