This article helps you resolve the most common problems with the Xero integration: settings that will not save, accounts or tax rates that do not appear in the dropdowns, and transactions that do not reach Xero. It walks through each symptom, explains what Qoblex is checking, and tells you exactly where to look in the Xero settings.
After reading it you will know which field each error refers to, how to use the Sync Status tab to find and re-send a failed transaction, and what information to gather before contacting support.
Where to look first
The Xero settings open from Integrations, then Xero. Once your connection is set up, the page shows these tabs:
- Sales — sales ledger, sales payment account and rules, invoice batching, document status.
- Purchases — purchases ledger, expenses account, bill document status, bill payment account and rules.
- Manufacturing — the manufacturing ledger and its override rules.
- Inventory — Stock On Hand, Cost Of Goods Sold, Inventory Adjustments accounts, product sync and journal status.
- Tax mappings — maps each Xero tax rate to a Qoblex tax.
- Sync Status — the log of every transaction sent to Xero, with its status and any error.
Make one change at a time, click Save changes, then retry the affected sync. This keeps it clear which change fixed the problem.
The Save changes button is hidden on the Sync Status tab, because that tab is a report rather than a settings form. Switch to any other tab to save settings.
Reconnecting Xero
If Qoblex cannot reach your Xero account, the Xero page shows the message “Oops! It looks like we couldn’t connect to your Xero account.” together with a Click here to restore the connection link. Use that link to re-authorize Qoblex with Xero, then return to the settings.
A broken or expired Xero authorization stops both the settings (accounts and tax rates will not load) and transaction sync. Restore the connection before troubleshooting anything else.
Understanding the special account options
In every ledger dropdown, Qoblex adds two options above your Xero accounts:
- Do Not Sync — skip this posting. Lines routed to this option are not sent to Xero.
- Inherit — keep the default account or tracking already set higher up, instead of overriding it. This appears in override rules.
These are Qoblex routing options, not Xero ledger accounts. All other entries in the list are your real Xero accounts, shown as their code followed by the account name.
Mapping accounts and tax rates with override rules
Each ledger section can have override rules. A rule sets the Set ledger account to and, optionally, the Set tracking category to value used when a transaction matches it. Rules are applied in priority order, so the first matching rule wins.
When you build a rule, the ledger account is required; the tracking category is optional. If you leave a rule’s ledger account empty, Qoblex shows “Ledger account is required” and the settings will not save.
Troubleshooting
Save changes is blocked on the Sales tab
The Sales tab requires a sales ledger, an invoice document status, and a payment bank account before it can save. Open the tab and fill any empty selector:
- A missing ledger shows “Ledger account is required”.
- A missing payment account shows “Bank account is required”.
Also check that every sales override rule and payment rule has a ledger account selected.
Save changes is blocked on the Purchases tab
The Purchases tab requires a purchases ledger, an Expenses Account, a bill document status, and a payment bank account. Open the tab and fill any empty selector (“Ledger account is required” or “Bank account is required” point to the missing field), then check that each payment rule has a ledger account.
Save changes is blocked on the Inventory tab
The Inventory tab requires the Stock On Hand Account, the Cost Of Goods Sold account, the Inventory Adjustments account, and a journal status. Missing selections show “SOH Account is required”, “COGS Account is required”, or “Adjustments Ledger Account is required”. Fill the missing account, then check that each COGS and adjustments override rule has a ledger account.
Save changes is blocked on the Tax mappings tab
Tax mapping needs at least one row, and every row must have both a Xero tax and a Qoblex tax name selected. An incomplete or empty mapping shows “Each row needs a Qoblex tax name and a Xero tax rate.” Complete or remove the offending row, then save again.
A ledger, bank, tax rate, or tracking category is missing from a dropdown
The dropdowns are built from the data Qoblex loads from your Xero organization, so a missing entry usually means it does not exist (or is archived) in Xero, or was created after you opened the page. Confirm the account, tax rate, or tracking category exists and is active in Xero, then reopen the Xero settings page so Qoblex reloads the organization data. If nothing loads at all, the Xero connection is probably broken — use the Click here to restore the connection link first.
Transactions do not appear in Xero
Open the Sync Status tab and use the filters to find the transaction by Type or Created at. The Status column tells you whether it is pending, failed, or already synced. If it failed, fix the cause (the mapping, tax setup, or source document), then select the row and click Sync to Xero. If it is already synced, the Xero link column links to the record in Xero — review it there rather than re-sending.
[!info] A transaction may simply be hidden by the current Type or Created at filter. Clear or widen the filters before concluding that a transaction is missing.
A tax error occurs during sync
Open the Tax mappings tab and confirm the Xero tax rate used by the failed transaction is mapped to a Qoblex tax. Add the missing mapping, save, then reselect the row on Sync Status and click Sync to Xero. Tax errors often surface only the first time a particular tax rate is used, so check the tax on the source document lines as well as the mapping row.
A payment posts to the wrong account
Payments post to the default payment bank account on the Sales or Purchases tab unless an override rule matches. Check the default account first, then review the payment rules. Because the first matching rule wins, a broad rule placed above a more specific one can capture payments you intended to route elsewhere — reorder the rules so the specific ones sit higher.
COGS or adjustments post to the wrong account
Open the Inventory tab and check the default Cost Of Goods Sold account and Inventory Adjustments account, then review the COGS and adjustments override rules. Rules are evaluated in priority order, so reorder them if a broad rule is overriding a specific one.
Manual sync shows “No transactions selected”
The Sync to Xero button on the Sync Status tab acts on the rows you select. If none are selected, Qoblex shows “No transactions selected. Please select at least one transaction to sync.” Tick at least one row, then click Sync to Xero again.
A manual sync still fails after retrying
Read the error Qoblex returns on the failed row — it names the missing mapping or the invalid source document. Correct that, then reselect the row and click Sync to Xero. After retrying, refresh the Sync Status list to confirm whether the row is now synced or still failing for a different reason.
The Xero page only shows the setup wizard, not the tabs
A newly connected Xero integration opens in a setup wizard that steps through Tax mappings, Sales, Purchases, Manufacturing, and Inventory before a final review. The full tabbed settings (including Sync Status) appear only after you complete and confirm the wizard. Finish every required step and confirm the review to switch to the normal settings view.
Have this ready so support can reproduce the issue quickly:
- the connected Xero organization name (shown on the Xero settings header);
- the tab where the problem occurs;
- the transaction type and number from Sync Status, and the row’s status;
- the exact error message shown;
- the relevant account, tax, or tracking mapping involved;
- the most recent settings change you made before the problem started, especially to tax mappings, payment accounts, or inventory accounts.
