Troubleshooting SQL Server connectivity
Symptom-first troubleshooting for Microsoft SQL Server connectivity - HYT00 login timeouts, 08001 handshake resets, TCP failures and redirects, authentication errors, private link stalls, and agent hangs.
Resolve common Microsoft SQL Server connectivity issues when integrating SQL Server with Atlan. Symptom-first, ordered by how often each issue actually occurs. Each entry includes a check you can run yourself before opening a ticket.
Quick index
| You see | Most likely cause | Jump to |
|---|---|---|
HYT00 - Login timeout expired on Test Authentication | No network path - IP not allowlisted, or private hostname | Login timeout |
08001 handshake error / TCP Provider: Error code 0x2746 (10054) | Firewall or load balancer resetting the connection - not TLS | Handshake resets |
| "The TCP/IP connection to the host ..., port 1433 has failed" | Security group / cross-region / redirect target blocked | TCP failures |
"Authentication failed" / Login failed for user (18456) | Missing database user or grants - or a network error in disguise | Authentication |
| Private link built, but connections time out | Pending approval, wrong Host value, or unhealthy LB target | Private link |
| SDR/agent run shows "running" for many hours, then times out | Agent-side worker/framework issue - not your network | Agent runs hang |
| Crawl succeeds but returns only database/schema names | Permissions, not connectivity | Only names crawled |
| Worked for months, broke with no change on your side | Egress address change on the Atlan side | Sudden breakage |
Login timeout expired (HYT00)
Symptom. Test Authentication fails after a long pause:
app internal error: 500 - map[details:Connection timed out: (pyodbc.OperationalError)
('HYT00', '[HYT00] [Microsoft][ODBC Driver 18 for SQL Server]
Login timeout expired (0) (SQLDriverConnect)')
Why. The connection attempt got no answer at all. Despite the word "Login", this error fires before any login happens - it means no network path exists. The two big causes, in order of frequency: Atlan's egress IPs aren't allowlisted on your firewall, or the hostname is private (only resolvable inside your network - check for .local or internal DNS names).
Fix. Confirm the hostname resolves publicly (nslookup <host> from any machine outside your network). If it doesn't, switch to a private link or the self-deployed runtime - no firewall change will fix a private name. If it does resolve, work through all four firewall layers with your tenant's egress IPs.
Handshake errors and TCP resets (08001 / 0x2746)
Symptom. One of these, often intermittent or affecting only some hosts:
('08001', '[08001] [Microsoft][ODBC Driver 18 for SQL Server]
Client unable to establish connection because an error was encountered
during handshakes before login. ...(26) (SQLDriverConnect)')
-- or:
('08001', '[08001] [Microsoft][ODBC Driver 18 for SQL Server]
TCP Provider: Error code 0x2746 (10054) (SQLDriverConnect)')
Why. The TCP connection opened and was then reset before login - the signature of a firewall, load balancer, or middlebox accepting the connection and then dropping an unrecognized source IP. These errors are repeatedly misdiagnosed as TLS/certificate/driver problems, costing weeks; engineering analysis in one support case proved the server closed the connection before the client sent a single byte. The connector's TLS settings relax certificate validation, so a certificate is almost never the cause.
Fix. Treat as an allowlist problem first: (1) confirm every IP in your tenant's egress list is allowlisted - a partial list fails intermittently as traffic rotates; (2) audit middleboxes between the internet and the database (edge firewalls, traffic managers, load balancers in a different VNet than the database); (3) only after both check out, involve support with a packet capture request.
"The TCP/IP connection to the host ... has failed"
{"errorName":"SOURCE_ERROR","errorMessage":"Cannot create PoolableConnectionFactory
(The TCP/IP connection to the host <server>, port 1433 has failed."}
-- or, note the redirect:
The TCP/IP connection to the host <server-2> (redirected from <server-1>),
port 2048 has failed. Error: "connect timed out ..."
Why and fix. Three causes from support history:
- Redirects - the "(redirected from ...)" form means SQL Server sent the client to a second host/port that your firewall doesn't allow. Allowlist the redirect target (host and port).
- Wrong tenant assumptions - the same database crawls fine from one Atlan tenant and fails from another, because each tenant has different egress IPs and possibly a different region. Allowlist per tenant.
- Cross-region security groups - a database in one cloud region with a tenant in another needs security-group/routing rules that permit the cross-region path.
"Authentication failed" and login errors
Symptom. A vague "Authentication failed" in the UI, or Login failed for user (SQL error 18456) in logs - while the same credentials work in SSMS.
Why. "Works in SSMS" only proves the credential is valid from inside your network. From Atlan, the same message can mean: (1) the network path fails first and gets reported vaguely; (2) an Entra service principal that was never created as a database user (CREATE USER ... FROM EXTERNAL PROVIDER missing); (3) NTLM without the Windows Domain field.
Fix, in order. First rule out network (does HYT00 or 08001 appear in the workflow logs?). Then apply the grants in Phase 3 of the direct guide. For NTLM, fill the domain field; to isolate variables, test once with a SQL-auth login.
Private link built, but connections time out
Check in this order - these were the actual root causes across private link support cases:
- Is the connection Approved? Pending endpoints time out silently. AWS: Endpoint services → Endpoint connections. Azure: Private Link Center (or the SQL server's Private endpoint connections blade). Nothing approves itself.
- Is the Host field right? It must contain the endpoint DNS name Atlan returned - not the PLS alias/service name you sent them, and not the public server name (unless support confirmed a DNS mapping). Compare character-by-character with your ticket.
- Is the load balancer target Healthy? (VM/EC2/RDS variants.) An unhealthy target means SQL Server isn't listening on the probed port or the OS firewall blocks the probe. For RDS: the instance IP may have changed - re-resolve and re-register, or move to RDS Proxy.
- Do NSG/SG rules allow Atlan's private CIDR? The public NAT IPs never appear on this path. On AWS, remember "Enforce inbound rules on PrivateLink traffic" is on by default.
- AZ mismatch? (AWS.) If Atlan's endpoint and your NLB share no availability zone and cross-zone load balancing is off, traffic has no route. Enable cross-zone load balancing or align AZs.
Agent (SDR) runs hang for hours, then time out
Symptom. A self-deployed runtime crawl shows "running" for many hours, then is marked timed out. Logs show no connection attempt to SQL Server at all.
Why. This is usually an agent-side issue - the run fails at its first internal step (worker registration / framework version mismatch) before any extraction begins - not your database or network. A related pattern: the extraction workflow isn't registered on the agent's worker (for example, after editing fields in the app YAML that must not be changed, such as app_name).
Fix. Don't burn days on your own firewall. Open a ticket with the run link and ask support to confirm (1) the agent build is on the current connector framework for SQL Server, and (2) the SQL Server worker is registered and polling. If you recently edited the agent's app YAML, mention exactly what changed.
Crawl succeeds but returns only database/schema names
Why. Not connectivity. The login can see that databases exist (VIEW ANY DATABASE) but can't read metadata inside them - without proper permissions the crawler only fetches database and schema names.
Fix. Grant per-database CONNECT + VIEW DEFINITION (or server-level CONNECT ANY DATABASE + VIEW ANY DEFINITION) - scripts in Phase 3 of the direct guide.
It worked for months, then broke overnight
- Ask support whether your tenant's egress addresses changed. There is no published changelog for SQL Server egress values today, and an unannounced new range has caused a months-long intermittent outage before. This one question can save weeks.
- Ask your own network team whether a firewall or middlebox rule changed - compare against the values from your original setup ticket.
- Check whether the failures are time-of-day or intermittent - that pattern suggests a partial allowlist (some of the tenant's IPs allowed, others not).
Opening ticket that gets solved fast
Include these seven things - tickets containing them consistently resolve in one or two replies instead of weeks:
- Your Atlan tenant URL and a link to the failing workflow run
- The exact error text from the workflow logs (not a paraphrase - the ODBC code matters)
- Where SQL Server runs (on-prem / Azure VM / Azure SQL DB / MI / RDS / EC2) and its network posture (public, "Selected networks", private endpoint, behind a partner firewall)
- Connectivity method (direct / private link / agent) and, for private link, the endpoint DNS name in use
- The hostname and port configured in the crawler
- The authentication method (basic / service principal / NTLM+domain)
- Whether it ever worked - and if so, when it stopped and what (if anything) changed