Error Codes

Syntra ODBC returns structured error messages that include an error code, a human-readable message, and when applicable, details from QuickBooks Desktop. This page lists all error codes and their resolutions.

Error Code Format

Errors follow this format:

SYNTRA-XXXX: Description

Connection Errors (1000–1099)

Code	Message	Resolution
SYNTRA-1000	Connection refused	Syntra service is not running. Start it via net start SyntraODBC.
SYNTRA-1001	Authentication failed	Check username/password in your connection string against config.toml.
SYNTRA-1002	Too many connections	Close idle connections or increase max_connections in config.toml.
SYNTRA-1003	TLS handshake failed	Verify TLS is configured correctly. See TLS Security.
SYNTRA-1004	Connection timeout	Syntra is overloaded or unresponsive. Check service status and logs.

Query Errors (2000–2099)

Code	Message	Resolution
SYNTRA-2000	Syntax error	Check your SQL syntax. Syntra uses PostgreSQL-compatible SQL.
SYNTRA-2001	Table not found	Run SHOW TABLES; to see available tables. Names are lowercase.
SYNTRA-2002	Column not found	Run SHOW COLUMNS FROM tablename; to see available columns.
SYNTRA-2003	Type mismatch	Ensure values match column types (e.g., dates as strings '2025-01-01').
SYNTRA-2004	Query timeout	The query took too long. Add WHERE/LIMIT clauses or check QuickBooks responsiveness.
SYNTRA-2005	Unsupported operation	The requested SQL feature is not supported for this table.

QuickBooks Errors (3000–3099)

These errors originate from the QuickBooks COM SDK (QBFC):

Code	Message	Resolution
SYNTRA-3000	QuickBooks not running	Open QuickBooks Desktop with the company file before running write operations.
SYNTRA-3001	QuickBooks access denied	Authorize Syntra in QuickBooks: Edit > Preferences > Integrated Applications.
SYNTRA-3002	Company file locked	Another application or user has exclusive access. Switch to multi-user mode.
SYNTRA-3003	Record not found	The ListID or TxnID does not exist in QuickBooks. Verify the ID.
SYNTRA-3004	Required field missing	The INSERT/UPDATE is missing a field required by QuickBooks. Check QB field requirements.
SYNTRA-3005	Duplicate record	A record with the same key already exists (e.g., duplicate customer name).
SYNTRA-3006	Record in use	The record is being edited in QuickBooks. Close it and retry.
SYNTRA-3007	Void failed	The transaction cannot be voided (e.g., it is already voided or linked to other transactions).

Cache Errors (4000–4099)

Code	Message	Resolution
SYNTRA-4000	Cache not ready	Initial sync is still in progress. Wait for it to complete.
SYNTRA-4001	Cache corruption detected	Run CALL qb_rebuild_all(); to rebuild the cache from scratch.
SYNTRA-4002	Sync failed	Incremental sync encountered an error. Check logs and QuickBooks availability.
SYNTRA-4003	Disk space insufficient	Free disk space on the drive hosting the cache file.

License Errors (5000–5099)

Code	Message	Resolution
SYNTRA-5000	License not activated	Activate your license. See License Activation.
SYNTRA-5001	License expired	Renew your Syntra ODBC subscription.
SYNTRA-5002	Feature not available	This feature requires a higher QuickBooks edition. For example, live reads require QuickBooks Enterprise.
SYNTRA-5003	License limit exceeded	Your license has reached its connection or table limit. Upgrade or close connections.

Getting Help

If you encounter an error not listed here or cannot resolve an issue:

1. Check the full error details in C:\ProgramData\SyntraODBC\logs\syntra.log.
2. Include the error code and log excerpt when contacting support.