Help & Common Errors

Solutions for the most common issues when importing data to QuickBooks Online

Connection & Authentication Issues

QuickBooks Connection Expired
Your authorization token has expired and needs to be refreshed
Authentication

What it means: QuickBooks Online tokens expire periodically for security. When this happens, you need to reconnect.

How to fix:
1
Click the Disconnect button in the top right corner
2
Click Connect to QuickBooks and sign in with your Intuit credentials
3
Authorize QBO Link to access your company file
4
Retry your import
Tip: If you frequently get disconnected, check that your QuickBooks Online subscription is active and your Intuit account is in good standing.

Special Characters

Special Characters in Names (Error 4000)
Apostrophes, quotes, or ampersands causing parsing errors
Special Characters

What it means: QuickBooks has trouble with certain characters in names. The most common issues are:

  • Apostrophes (') - e.g., "O'Brien", "Joe's Shop"
  • Double quotes (") - e.g., "The "Best" Product"
  • Ampersands (&) - e.g., "Smith & Jones"
How to fix:
1
Open your IIF file in a text editor (Notepad++ recommended)
2
Use Find & Replace to fix problematic characters:
O'Brien → O Brien (or OBrien)
Smith & Jones → Smith and Jones
"Best" Product → Best Product
3
Save the file and retry the import
Note: QBO Link attempts to handle common special characters automatically, but some combinations may still cause issues. If the automatic handling fails, manual editing is required.

Duplicate Records

Record Already Exists
Trying to create a record that already exists in QuickBooks
Validation

What it means: QuickBooks found an existing record with the same name. QBO Link will attempt to update the existing record instead of creating a duplicate.

How it works:
  • Customers - Matched by Display Name
  • Items - Matched by Name
  • Accounts - Matched by Name

If a match is found, the existing record is updated with data from your IIF file. This is shown as "SUCCESSFUL UPDATES" in the results.

Tip: If you want to create new records with similar names, add a suffix (e.g., "John Smith - New") to make them unique.

Missing References

Account/Item/Customer Not Found
Your file references something that doesn't exist in QuickBooks
Missing Reference

What it means: Your IIF file contains a reference (like an account number, customer name, or item name) that doesn't exist in your QuickBooks Online company.

Import Order Matters!

Always import data in this order:

  1. Accounts (Chart of Accounts) - first, as everything else references these
  2. Customers - before transactions that reference them
  3. Items (Products/Services) - before transactions that use them
  4. Transactions (Invoices, Payments, etc.) - last, after all references exist
How to fix:
1
Check the error message for the specific name/number that's missing
2
Import the missing data type first (accounts, customers, or items)
3
Then retry importing your transactions

Product Hierarchy Issues

Parent/Child Item Hierarchy Conflict
Sub-items reference parents that don't exist, or category items have prices
Hierarchy

What it means: QuickBooks Online has strict rules about parent/child product relationships that differ from QuickBooks Desktop.

QBO Rules:
  • Category items (parents) cannot have prices or be sold directly
  • Sub-items (children) can have prices and be sold
  • An item cannot be both a category AND a sellable product
  • Parent items must exist before sub-items can be created
How to fix:
1
Use Validate Only mode to identify hierarchy issues before importing
2
Import parent/category items first (without prices)
3
Import sub-items second (with prices)
4
If a "top-level" item needs to be sold, make it a regular item instead of a category
FBO Director users: FBO allows selling category products directly. When exporting to QBO, you may need to restructure your product hierarchy.

Rate Limits

Rate Limit Exceeded
Too many requests sent to QuickBooks in a short time
Rate Limit

What it means: QuickBooks Online limits how many API requests can be made per minute/hour to prevent system overload.

How to fix:
1
Wait 2-3 minutes before retrying
2
For large imports, consider splitting your file into smaller batches (e.g., 500 records at a time)
3
If importing multiple file types, wait a few minutes between each import
Note: QuickBooks typically allows 500 requests per minute. Large files with thousands of records may hit this limit.

File Format Issues

Invalid IIF File Format
The file structure doesn't match expected IIF format
File Format

What it means: IIF files have a specific structure. The file may be corrupted, saved incorrectly, or not be a true IIF file.

IIF File Requirements:
  • First line must start with a header (e.g., !ACCNT, !CUST, !INVITEM, !TRNS)
  • Fields are tab-separated (not comma-separated)
  • File should be plain text (not Excel format)
How to verify your file:
1
Open the file in Notepad (right-click → Open with → Notepad)
2
Check that the first line starts with an exclamation mark (!)
3
Ensure fields are separated by tabs, not commas
4
Re-export from FBO Director or QuickBooks Desktop if the file appears corrupted

Server & Connection Errors

Server Error / Connection Failed
QuickBooks Online or network issue
Connection

What it means: The connection to QuickBooks Online failed. This could be a temporary issue with Intuit's servers or your internet connection.

How to fix:
1
Check your internet connection
2
Wait a few minutes and try again - server issues are usually temporary
3
Check Intuit's status page for known outages
4
If the problem persists, try disconnecting and reconnecting to QuickBooks

Tax & Class Issues

Tax Code or Class Not Found
Referenced tax code or class doesn't exist in QuickBooks
Tax/Class

What it means: Your file references a tax code or class that hasn't been set up in QuickBooks Online.

For Tax Codes:
  • QBO tax codes are managed in Settings → Taxes
  • Tax names must match exactly (case-sensitive)
  • Consider using the "Use QBO Tax Rates" option if you have a simple tax setup
For Classes:
  • Classes must be enabled in QBO Settings → Advanced → Categories
  • Create classes in QBO before importing transactions that use them
  • Class names must match exactly

Other Issues

Getting More Help
What to do when you're stuck
Support

If you're experiencing an issue not covered above:

Before contacting support:
1
Check the Import History for the Correlation ID
2
Note the exact error message and when it occurred
3
Try the Validate Only option to see detailed file analysis
4
Check the video tutorials for step-by-step guidance
Contact Support

Visit our Support page for contact information and troubleshooting tips.

When contacting support, please include:

  • Your Correlation ID (shown after each import)
  • The error message you received
  • What you were trying to import (accounts, customers, items, transactions)
  • A sample of the problematic records (if possible)

Required Fields Reference

Accounts
  • Name (required)
  • Account Type (required)
  • Account Number (optional)
Customers
  • Display Name (required)
  • All other fields (optional)
Items
  • Name (required)
  • Income Account (required)
  • Price, Description (optional)
Transactions
  • Date (required)
  • Customer (required)
  • At least one line item
Quick Links
Connection Issues Special Characters Duplicate Records Missing References Product Hierarchy Rate Limits File Format Server Errors Tax & Classes Required Fields
Contact Support Getting Started Wizard Video Tutorials View Import History