Troubleshooting

QuickBooks reports problems through the ODBC driver, and the text you get describes the driver’s internals rather than your situation: 517, 401 Authorization Required, a file must be specified. Each one has essentially a single cause on a real machine, and none of them says what it is.

The connector already translates these where it can — when a connection test fails it shows the likely cause and the fix first, and the driver’s raw text underneath. This page is that same advice, in the same words, so an error you read in the app leads you somewhere that matches.

Find your message below. They’re grouped by where the problem actually lives.

The driver and Windows

”Data source name not found and no default driver specified” — or IM002

What it means: Windows has no DSN by that name.

What to do: Create a System DSN with this exact name in the 64-bit ODBC Data Source Administrator. A User DSN is not enough when the connector runs as a Windows service — the service does not run as you. Check the spelling against the DSN name field in the connector; it has to match character for character.

Error 193, 0x000000C1, or “not a valid Win32 application”

What it means: The driver and the connector are different architectures.

What to do: Both must be 64-bit. Install the 64-bit driver, and create the DSN in the 64-bit ODBC Data Source Administrator (C:\Windows\System32\odbcad32.exe, not SysWOW64).

On Windows on ARM this error can also come from the shell you’re using rather than from the install. The driver is an x64 binary running under emulation; if you’re testing from PowerShell and hitting 193, try the x64 build of PowerShell 7.

Anything mentioning libodbc or unixODBC

What it means: The connector cannot find an ODBC driver manager on this machine.

What to do: The QuickBooks drivers are Windows-only. Run the connector on the Windows machine where QuickBooks is installed.

The gateway

517 ... 401 Authorization Required

What it means: The QuickBooks Desktop Gateway rejected the user and password. (On QODBC, the Remote Connector rejected them.)

What to do: Check the username and password in the connector against the gateway user in the CData QuickBooks Desktop Gateway. Even a “direct” DSN goes through the gateway, so it will not connect without one — if you never created a gateway user, that’s the answer.

”No connection could be made because the target machine actively refused it” — or “Unable to connect to the remote server”

What it means: Nothing is listening where the driver expects the gateway.

What to do: Start the QuickBooks Desktop Gateway service on this machine and check the URL on the DSN — it is http://localhost:8166 by default. If the gateway’s tray icon is visible and you’re still getting this, check whether the service and the tray application are fighting over the port; only one of them can hold 8166.

QuickBooks itself

517 ... If no file is open in QuickBooks, a file must be specified

What it means: QuickBooks is not open on a company file, and the connection does not name one.

What to do: Open QuickBooks on the company file and leave it open, or set the company file path on the DSN. The drivers read through QuickBooks itself, so it cannot be closed unless the DSN says which file to open.

”QuickBooks already has a company file open”

What it means: QuickBooks is open, but on a different file — or at a different elevation.

What to do: Two things produce this. Either the company file path on the DSN does not match the file QuickBooks has open (leave it blank to use whatever is open), or QuickBooks was started with “Run as administrator” while the gateway was not. Both must run at the same elevation.

The second cause is the one that wastes time, because the message points squarely at the first. If the path is already blank, stop looking at paths: close QuickBooks, reopen it by double-clicking normally, and try again.

”Could not start QuickBooks” or “QuickBooks is not running”

What it means: The driver could not get QuickBooks to respond.

What to do: Open QuickBooks on the company file, sign in, and leave it open. If it is already open, close it and reopen it without “Run as administrator."

"Not authorized,” “access has not been granted,” or anything about a certificate

What it means: QuickBooks has not been told to trust this connector.

What to do: In QuickBooks, with the company file open as the admin user, reconnect and answer the integrated application prompt with “Yes, always; allow access even if QuickBooks is not running.” The prompt appears once, on the QuickBooks window — it can sit behind other windows. The full lesson is here.

”QuickBooks cannot currently be accessed”

What it means: Usually nothing permanent — QuickBooks was busy, being reopened, or showing a dialog that blocks the company file.

What to do: Run it again. If it repeats, look at the QuickBooks window: a modal dialog waiting for someone will hold the file indefinitely.

Your queries

”is not a valid table” or “Invalid object name”

What it means: The query names tables this driver does not have.

What to do: CData and QODBC name their tables differently — CData has Customers, Items and InvoiceLineItems where QODBC has Customer, ItemInventory and InvoiceLine. Insert the starter query on the endpoint’s SQL step to get the set that matches the driver selected on the Source Connection page.

If starter queries keep producing this, the QuickBooks driver setting doesn’t match the driver actually installed. Fix the setting first, then re-insert the starter query.

An error about FromModified, or converting a date value around 1900

What it means: QuickBooks refused the date the query asked it to compare against.

What to do: QuickBooks will not accept dates that far in the past. Update the connector — current versions bound a first run to the last 24 months.

When none of these match

The raw driver text is kept for exactly this case, and it’s what a support conversation needs. Send it as it appears, along with which driver you’re using, whether QuickBooks was open, and what you were doing — and get in touch. An unrecognized message is left to stand on its own rather than wrapped in a guess, so if the connector showed you no advice, that’s the situation you’re in and it isn’t your mistake.