Common Issues

Connection Issues

401 Authorization Error — "AuthorizationFault"

The OAuth token has expired or been revoked. QuickBooks tokens expire periodically, and any changes to your Intuit account credentials can also invalidate them.

Fix:

1. Go to your Coupler.io data flow settings.

2. Click the source connection and select Reconnect.

3. Sign in again with your Intuit/QuickBooks credentials and re-authorize.

If the Reconnect option doesn't appear, remove the existing QuickBooks connection from Settings → Connections and create a new one.

QuickBooks Desktop is not supported

Coupler.io connects to the QuickBooks Online API only. If you have QuickBooks Desktop (including Desktop Enterprise), the integration will not work.

Fix: You would need to migrate your data to QuickBooks Online, or use a third-party sync tool that bridges QuickBooks Desktop to an online-accessible format.

Connection works but data flow fails on subsequent runs

This usually means the OAuth token refreshed successfully but QuickBooks returned an API error. Check the error details in the data flow run history.

Fix: Open the data flow, click on the failed run, and expand the error details. Common causes include changed permissions, a deleted entity, or API rate limits.

Missing Data

Only active records are returned (missing inactive vendors, customers, etc.)

By default, QuickBooks API queries return only active records. Inactive vendors, customers, or items won't appear unless you explicitly request them.

Fix: Add Active IN (false, true) to the Where parameter to include both active and inactive records.

Budget entity returns metadata but no line-item amounts

The QuickBooks Budget entity returns budget-level metadata (name, fiscal year, type) but the detailed line items (monthly amounts per account) come in a nested format that isn't broken out into columns automatically.

Fix: There is currently no built-in way to fully flatten budget line items in Coupler.io. As a workaround, export the Budget entity and process the nested fields in your destination using formulas or a transformation step.

P&L report returns data for wrong date range

Some users set a custom report period (e.g., starting January 2021) but only receive data from a more recent period.

Fix: Make sure you select Custom as the Report period and then enter both the Start date and End date explicitly. Also check that your QuickBooks company file actually contains data for the requested period.

Invoice or transaction data is missing line-item detail

When exporting invoices or other entities with multiple line items, each record may appear as a single row with aggregated data.

Fix: Set the Split by parameter to Line. This splits multi-line documents into separate rows — one row per line item.

Permission Errors

"Access denied" or missing entities

Some QuickBooks entities require specific subscription tiers or features to be enabled (e.g., Classes require QuickBooks Plus or Advanced, Budget requires Plus or Advanced).

Fix: Verify your QuickBooks Online subscription tier supports the entity you're trying to export. Also ensure the connected account has Admin or Accountant-level access.

Data Discrepancies

Reports show Cash basis instead of Accrual (or vice versa)

QuickBooks Reports default to the accounting method set in your company preferences. If you're getting Cash-basis data when you expect Accrual, the report is inheriting the default.

Fix: Add the query parameter accounting_method: Accrual (or Cash) in the Query parameters field. This overrides the company default for that specific report.

Report totals don't match QuickBooks Online

Small differences between Coupler.io exports and the QuickBooks UI can occur when the report covers a different date range, uses a different accounting method, or includes/excludes certain transaction types.

Fix:

1. Confirm the report period and start/end dates match exactly.

2. Check the accounting_method parameter.

3. Verify Display columns by is set the same way (Total vs. Month can affect how subtotals appear).

4. For multicurrency accounts, check whether the report includes or excludes currency conversion adjustments (adjusted_gain_loss parameter).

General Ledger doesn't show split transaction detail

The General Ledger Detail report may show "Split" in the Split column instead of the actual accounts involved when a transaction is split across multiple accounts.

Fix: Use the Transaction List with Splits report instead. This report outputs each split as a separate row, showing the actual GL account or class for each portion of the transaction.

Rate Limits and API Errors

400,000-cell limit error — report data is truncated

The QuickBooks Reports API enforces a hard limit of 400,000 cells (rows × columns). When a report exceeds this, QuickBooks truncates the response or injects an error message like "Unable to generate report."

Fix:

• Narrow the date range (e.g., pull monthly instead of yearly).

• Reduce the number of columns selected.

• Filter by class, department, or customer to reduce the data volume.

• Split the report across multiple data flows with non-overlapping date ranges.

The 400,000-cell limit is a QuickBooks API limitation, not a Coupler.io limitation. There is no way to increase it. If your General Ledger or Transaction List consistently hits this limit, you must split your exports into smaller time ranges.

Data type mismatch errors when exporting to BigQuery

BigQuery requires consistent data types within a column. If QuickBooks returns mixed types (e.g., a "Num" column that contains both integers and strings like "JL07"), the import fails.

Fix: Use the Columns selector in Coupler.io to exclude problematic columns, or use a transformation step to standardize the data types before export.

Power BI error: "Key should not be null or empty"

This occurs when a column in the exported data has a blank or "Untitled" header. Power BI cannot parse columns without proper names.

Fix:

1. Open the data flow in Coupler.io.

2. Go to the Transform step.

3. Rename any blank or "Untitled" column headers.

4. Re-run the data flow and refresh the Power BI connection.