> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/finance-and-accounting/quickbooks/common-issues.md).
# 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.
Line items are concatenated in one column and row
When exporting Invoices, Bills, or other entities with multiple line items with the **Split by** parameter empty, you will get one row per invoice, bill (or whichever entity is selected), and will have the line items concatenated together like so:
To unnest or flatten this to give you one row per line item, set the **Split by** parameter to `Line` :
## 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.
{% hint style="danger" %}
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.
{% endhint %}
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.coupler.io/sources/category/finance-and-accounting/quickbooks/common-issues.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.