Common Issues

This page covers the most common issues users encounter with Syntra ODBC and how to resolve them.

Connection Issues

”Connection refused” when connecting to Syntra

Cause: The Syntra service is not running, or it is listening on a different port.

Solutions:

1. Check that the Syntra service is running: Get-Service SyntraODBC in PowerShell.
2. Verify the port in config.toml matches what your client is using (default: 5433).
3. Check the Windows Firewall is not blocking port 5433.
4. Review the log at C:\ProgramData\SyntraODBC\logs\syntra.log for startup errors.

”Authentication failed”

Cause: Incorrect username or password.

Solutions:

1. Verify your credentials match those in config.toml.
2. The default username is qbconnect. Passwords are case-sensitive.
3. If you recently changed the password in config.toml, restart Syntra ODBC for the change to take effect.

”ODBC driver not found” in ODBC Data Source Administrator

Cause: The ODBC driver was not registered during installation, or there is a 32-bit/64-bit mismatch.

Solutions:

1. Re-run the Syntra installer to register the driver. The installer sets up both a 64-bit and a 32-bit Syntra ODBC - QuickBooks ODBC driver and two matching DSNs (Syntra QuickBooks 64-bit and 32-bit).
2. If your application is 32-bit (e.g., older Excel, Crystal Reports), open the 32-bit ODBC administrator at C:\Windows\SysWOW64\odbcad32.exe and confirm the 32-bit Syntra QuickBooks DSN is listed on the System DSN tab.
3. Verify syntra-odbc.dll is present in the Syntra installation drivers\x64\ and drivers\x86\ subdirectories.

QuickBooks Issues

”QuickBooks is not running” error on write operations

Cause: Write operations (INSERT, UPDATE, DELETE) require QuickBooks Desktop to be open with the company file loaded.

Solutions:

1. Open QuickBooks Desktop and ensure the correct company file is active.
2. Verify QuickBooks is running under the same Windows user account as the Syntra service.
3. Check that Syntra is authorized in QuickBooks: Edit > Preferences > Integrated Applications.

”QuickBooks access denied”

Cause: Syntra has not been authorized in QuickBooks, or the authorization was revoked.

Solutions:

1. In QuickBooks, go to Edit > Preferences > Integrated Applications > Company Preferences.
2. Find Syntra ODBC in the list and ensure it has access.
3. If not listed, restart the Syntra service. QuickBooks should display an authorization prompt.
4. Make sure QuickBooks is not in single-user mode if multiple applications need access.

QuickBooks crashed and is stuck on an unrecoverable error dialog

Cause: QuickBooks Desktop crashed during a live request and is waiting on one or more modal dialogs before it can fully exit and reopen.

Solutions:

1. In Syntra, open Settings > QuickBooks and enable Auto-recover QuickBooks after a crash.
2. Set Company file to the exact .QBW you want Syntra to reopen.
3. Fill the QuickBooks login fields in Syntra if your company file prompts for a username, password, or both.
4. Verify Syntra has permanent QuickBooks authorization under Edit > Preferences > Integrated Applications.
5. See QuickBooks Crash Recovery for the full recovery setup and requirements.

Stale data / cache not updating

Cause: Incremental sync may have stalled, or the table’s polling tier is set to a long interval.

Solutions:

1. Force a sync: CALL qb_sync_table('tablename');
2. Rebuild the entire cache: CALL qb_rebuild_all();
3. Check the cache status: SELECT * FROM qb_cache_status;
4. Verify QuickBooks is running, as cache sync requires an active QuickBooks instance.

Query Issues

”Table not found” error

Cause: The table name may be misspelled, or the cache has not completed its initial sync.

Solutions:

1. Run SHOW TABLES; to see all available tables.
2. Table names are lowercase: use customers, not Customers.
3. If the Syntra service just started, wait for the initial sync to complete.

Slow queries

Cause: Query is hitting the live QBFC path instead of the cache, or the query scans too much data.

Solutions:

1. Remove SET QB_MAX_STALENESS = 0 unless you specifically need live data.
2. Add WHERE clauses to limit the data scanned.
3. Use LIMIT for exploratory queries.
4. See Performance for detailed tuning advice.

Custom fields not appearing

Cause: Custom fields are discovered during sync. New custom fields require a cache rebuild.

Solutions:

1. Run CALL qb_rebuild_all(); to rediscover custom fields.
2. Ensure at least one record in QuickBooks has a value set for the custom field.
3. See Custom Fields for details.

Service Issues

Service fails to start

Cause: Configuration error, port conflict, or missing files.

Solutions:

1. Check the log file at C:\ProgramData\SyntraODBC\logs\syntra.log.
2. Verify config.toml is valid TOML syntax.
3. Ensure port 5433 is not in use by another application: netstat -an | findstr 5433.
4. If running as a specific user, verify that account has the “Log on as a service” right.

Service stops unexpectedly

Solutions:

1. Check Windows Event Viewer (Application log) for crash details.
2. Review the Syntra log for error messages before the stop.
3. Configure automatic restart in the service Recovery settings.
4. Ensure sufficient disk space for the cache file.

Where are the logs?

Syntra ODBC writes a rolling log to %ProgramData%\SyntraODBC\logs\syntra.log. You can tail that file with any text editor when you need deep diagnostics. For day-to-day troubleshooting, the Syntra ODBC app has a built-in Log tab that shows the same log stream live, with filters and search:

Use the Log tab to:

• Watch a write operation land in real time. Every insert_record, update_record, and delete_record call prints the generated qbXML request/response, which is what you want when a QuickBooks error code is unclear.
• Confirm cache syncs. Fetched bills, Fetched charges, Fetched invoices messages appear as the background sync engine pulls each entity.
• Trace schema operations. Scanning QueryRoot, Building xsd schema for update/insert into ... messages appear when Syntra introspects QuickBooks to build its writable-column map for a new entity.
• Filter by level. The tab has buttons for TRACE, DEBUG, INFO, WARN, ERROR. Start at INFO for normal diagnostics; drop to DEBUG or TRACE when you need more detail. The log level also controls what gets written to disk, via the [logging] level key in config.toml.

When reporting an issue to support, copy the relevant 20-30 lines from around the error and attach them to your report. The Log tab’s search makes it easy to jump to the first ERROR or WARN line.