Troubleshooting
Symptom-first troubleshooting for the DLH.io SQL Server Agent: connectivity, ODBC, licensing, Change Tracking, schema drift, storage, memory and scheduling problems, plus what to send to support.
Start here
- Run
dlh_agent_sql_server.exe --diagnoseon the host. It checks the same things a run would (configuration, credentials, ODBC, SQL Server, CT/CDC, platform bootstrap, storage, state store, disk and memory) without extracting anything, and prints PASS, WARN or FAIL per check. Most problems below show up here. - Open the newest log in
logs\(or the shipped copy underlogs/<date>/run_<id>/in your object storage) and read the run summary at the bottom, then theERRORSlist, then the per-table lines for the failing table. - Compare the tier banner and state store telemetry block near the top of the log with what you expect.
The sections below are organized by what you see.
Startup and configuration
ODBC and SQL Server connectivity
Tier, license and bootstrap
Change Tracking and CDC
Schema drift and type errors
Storage and output
Performance and memory
Notifications and lifecycle actions
When to contact support
If the steps above do not resolve the issue, send the following through your support channel or /contact:
- Output of
dlh_agent_sql_server.exe --diagnose --json > diagnose.json. - The failing run's log from object storage (
logs/<date>/run_<id>/), which is already redacted, or the local log with passwords and tokens removed. - The
run_<id>_summary.jsonfrom the same folder. - Your
dlh_agent_config.yamlwith thedlh_ref.dlh_api_key, storage keys and webhook URLs replaced by placeholders. Never send.secor.keyfiles. - The agent version (
--version), Windows version, SQL Server version and edition, and whether the target is Delta or Iceberg.
Defect or environment?
A useful rule: if --diagnose reports FAIL, the problem is in the environment (network, credentials, driver, disk, permissions) and the fix is on the host. If --diagnose is clean but a specific table fails on every run with the same error, that is a data or schema issue and the log's per-table error names it. If runs fail intermittently with different tables each time, look at memory, SQL Server blocking and network stability before anything else.