# Common Issues
## Connection Issues
OAuth token expired — reconnection required
Xero OAuth tokens can expire or be revoked if your Xero credentials change, if you remove the Coupler.io app from your Xero account, or after prolonged inactivity.
**Fix:**
1. Go to your Coupler.io data flow settings.
2. Click the source connection and select **Reconnect**.
3. Sign in again with your Xero credentials and re-authorize.
If the Reconnect option doesn't appear, remove the existing Xero connection from **Settings → Connections** and create a new one.
403 Forbidden error
This means the connected Xero account doesn't have sufficient permissions for the requested entity or tenant.
**Fix:**
1. Verify the connected account has Standard or Advisor access to the Xero organization.
2. Check that the correct **tenant** is selected in the data flow settings.
3. For Payroll entities, ensure the account has Payroll Admin access.
4. Reconnect if your permissions were recently updated — Coupler.io captures permissions at connection time.
New tenant not appearing in the dropdown
Coupler.io captures available tenants when the Xero connection is first created. If you add a new Xero organization after connecting, it won't appear automatically.
**Fix:** Go to **Settings → Connections**, remove the existing Xero connection, and create a new one. The new tenant will be available in the dropdown.
## Missing Data
Bank Transactions only shows reconciled data
The Xero Bank Transactions entity pulls only reconciled transactions. Unreconciled bank feed items are not accessible via the Xero API.
**Fix:** There is no workaround — this is a Xero API limitation. Ensure your bank transactions are reconciled in Xero before pulling data. Alternatively, use the Bank Statement report for a broader view of bank activity.
Invoice or journal data is missing line-item detail
When exporting invoices, credit notes, journals, or other entities with nested line items, each record appears as a single row with aggregated or concatenated data.
**Fix:** Set the **Split by** parameter to `LineItems` (for invoices, credit notes, bank transactions) or `JournalLines` (for journals). This splits multi-line documents into separate rows — one row per line item.
Detailed report type not available for my entity
The Detailed report type is only supported for Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments. All other entities only support the Simple report type.
**Fix:** If your entity doesn't support Detailed, use Simple and supplement with the **Split by** parameter if you need nested data expanded.
Account Transactions report is not available
The "Account Transactions" report that exists in the Xero UI is not available through Xero's API. This is one of the most common feature requests (11+ tickets).
**Fix:** As a workaround, use the **Journals** entity (for system-generated entries) or **Manual Journals** entity and filter by account. You can also combine the Invoices, Payments, and Bank Transactions entities to reconstruct transactional detail for specific accounts.
## Data Discrepancies
P&L report shows incorrect values for some months
Xero's API treats the End Date as the cutoff day for **every month** in the report. If you set the End Date to a month with only 30 days (e.g., September 30), all months in the report will only include data up to the 30th — losing one day from months with 31 days.
**Fix:** Always use an End Date in a month with 31 days:
* 12-31, 10-31, 08-31, 07-31, 05-31, 03-31, or 01-31
If the current month doesn't have 31 days, use the next month that does. For example, to get a P\&L through June, set the End Date to July 31.
{% hint style="danger" %}
The P\&L End Date issue is a Xero API limitation, not a Coupler.io limitation. This is the single most common Xero support question (14 tickets). Always use a 31-day month as your End Date (e.g., `2025-12-31`) to avoid this issue entirely for year-end reports.
{% endhint %}
Report totals don't match Xero UI
Small differences between Coupler.io exports and the Xero UI can occur when the report covers a different date range, includes/excludes cash-only transactions, or uses different tracking category filters.
**Fix:**
1. Confirm the **date range** matches exactly.
2. Check the **Include cash transactions only** toggle.
3. Verify **Tracking Category ID** and **Tracking Option ID** parameters match your Xero filter settings.
4. For Balance Sheet, note that the report shows data as of the **end of the month** regardless of the specific day selected.
Aged Payables/Receivables only shows one contact
The Aged Payables By Contact and Aged Receivables By Contact reports require a **Contact ID** parameter. They return data for only one contact per data flow. There is no "all contacts" option in the Xero API.
**Fix:** If you need aging data for all contacts:
1. Use the **Invoices** entity with status filters (AUTHORISED, for outstanding) as an alternative.
2. For a full aged report, you would need to create a separate data flow per contact — impractical for large contact lists.
3. Consider using the Purchase Orders or Invoice entities with date-based Where filters to approximate aging buckets.
## Rate Limits and API Errors
Xero API rate limit exceeded
Xero enforces API rate limits. If you have multiple data flows running simultaneously against the same Xero organization, you may hit rate limits causing temporary failures.
**Fix:**
* Stagger your data flow schedules so they don't all run at the same time.
* Reduce the frequency of data refreshes if you have many Xero data flows.
* Use the **Changed after** parameter to pull only recently modified records, reducing API calls.
Timeout error on large datasets
Data flows that pull very large volumes (e.g., thousands of journals or invoices) may time out, especially when using the Detailed report type or Split by parameter.
**Fix:**
* Use the **Changed after** parameter to limit the date range and reduce data volume.
* For Journals, use the **Journal number more than** / **Journal number less than** parameters to pull in batches.
* Switch from Detailed to Simple report type if you don't need the extended fields.
Data type mismatch errors when exporting to BigQuery
BigQuery requires consistent data types within a column. If Xero returns mixed types in a column, the import may fail.
**Fix:** Use a transformation step in Coupler.io to standardize data types before export, or exclude problematic columns using the column selector.
---
# Agent Instructions: 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:
```
GET https://docs.coupler.io/sources/category/finance-and-accounting/xero/common-issues.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.