Repository navigation
TCP Provider: Error code 0x2746 on Linux while trying to connect to Azure SQL #602
Description
Describe the bug
Connecting to Azure SQL from a Linux container hosted in AKS fails with a TCP connection reset during the TLS
handshake starting from mssql-python==1.5.0. The same code and connection string work with
mssql-python==1.4.0 from exactly the same hosting environment. The failure is independent of the base OS and OpenSSL version (tested on
Debian Bookworm and Debian Trixie — see matrix below).
Exception message:
mssql_python.exceptions.OperationalError: Driver Error: Communication link failure;
DDBC Error: [Microsoft]TCP Provider: Error code 0x2746
Stack trace:
File "mssql_python/db_connection.py", line 55, in connect
conn = Connection(
File "mssql_python/connection.py", line 378, in __init__
_raise_connection_error(e)
File "mssql_python/connection.py", line 89, in _raise_connection_error
raise exc from None
mssql_python.exceptions.OperationalError: Driver Error: Communication link failure;
DDBC Error: [Microsoft]TCP Provider: Error code 0x2746
To reproduce
Dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
libltdl7 libkrb5-3 libgssapi-krb5-2 \
&& rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir "mssql-python==1.5.0" azure-identityPython
import mssql_python
conn = mssql_python.connect(
"Server=tcp:<server>.database.windows.net,1433;"
"Database=<db>;"
"Authentication=ActiveDirectoryDefault;"
"Encrypt=yes;TrustServerCertificate=no;"
)The container runs on Kubernetes with Azure Workload Identity (azure.workload.identity/use: "true"),
so DefaultAzureCredential resolves via WorkloadIdentityCredential using the projected
AZURE_FEDERATED_TOKEN_FILE.
Expected behavior
Successful connection, as produced by mssql-python==1.4.0 under identical conditions.
Further technical details
Python version: 3.12 / 3.14
SQL Server version: Azure SQL Database
Operating system: Docker container (Linux)
Additional context
The regression seems to come from the compiled ddbc_bindings Linux binary — not in the OS,
OpenSSL version, or authentication layer.
Version matrix
| Base image | OpenSSL | mssql-python | Result |
|---|---|---|---|
python:3.12-slim (Debian Bookworm) |
3.0.x | 1.4.0 | ✅ connects |
python:3.12-slim (Debian Bookworm) |
3.0.x | 1.5.0 | ❌ 0x2746 |
python:3.12-slim (Debian Bookworm) |
3.0.x | 1.7.1 | ❌ 0x2746 |
python:3.14-slim-trixie (Debian Trixie) |
3.3.x | 1.4.0 | ✅ connects |
python:3.14-slim-trixie (Debian Trixie) |
3.3.x | 1.7.1 | ❌ 0x2746 |
What was ruled out
- The error occurs during the TLS handshake, before any authentication token is sent —
confirmed by the TCP-reset error code (0x2746=WSAECONNRESET). - Base OS / OpenSSL version is not the cause. The failure reproduces on Debian Bookworm
(OpenSSL 3.0.x) and Debian Trixie (OpenSSL 3.3.x).1.4.0connects successfully on both. - System OpenSSL configuration has no effect. Modifying
SECLEVEL, settingOPENSSL_CONF,
and excluding DHE cipher suites (!kDHE) all had no impact — theddbc_bindingsbinary
appears to be compiled withOPENSSL_NO_AUTOLOAD_CONFIGor the failing TLS path bypasses
config-controlled code entirely.
Related: #461 reports the same 0x2746 on Linux against a Fabric SQL endpoint (opened
March 2026, still open). This report demonstrates the issue also affects standard Azure SQL
Database.
Activity
github-actions commentedon May 27, 2026
Hi MartinLukas-oss, thank you for opening this issue!
Our team will review it shortly. We aim to triage all new issues within 24-48 hours and get back to you.
If you have additional information to share, please feel free to update the issue.
Thank you for your patience!
denys-nva commentedon May 28, 2026
I see the issue also happening in Microsoft Fabric Runtime 1.3 for
mssql-python == 1.7.1, previous version (1.6.0) didn't have the issue.OperationalError: Driver Error: Communication link failure; DDBC Error: [Microsoft]TCP Provider: Error code 0x2746subrata-ms commentedon May 29, 2026
Hi denys-nva , MartinLukas-oss
Acknowledge! I will start looking into this issue. I will provide an update early next week.
Thanks
Subrata
subrata-ms commentedon Jun 8, 2026
Hi MartinLukas-oss , This issue is not reproducible in our AKS environment. Below is my analysis on this issue -
Environment Setup and ran 20 test and all are successfully executed:
Validation-1 :: Customer comments: The regression seems to come from the compiled ddbc_bindings Linux binary — not in the OS,OpenSSL version, or authentication layer. "
Validation-2: Findings: 1.4.0 vs 1.5.0 — OpenSSL init pathway is unchanged"
"Validation-3: setup compression and validation"
With all the above validation, we are unable to reproduce the issue with multiple iterative runs. In-order to root cause the issue, we need more data. MartinLukas-oss is it possible to provide a docker image of the environment where this issue occurring?
We would like to verify following list of things to root cause the issue.
MartinLukas-oss commentedon Jun 8, 2026
How would I send you the full image?
The docker file is just this:
The container has to run with these security flags:
The dependencies are as following:
What else could be of interest?
We are targeting an Azure SQL Server via a Service Endpoint.
subrata-ms commentedon Jun 8, 2026
Hi MartinLukas-oss , thanks for sharing the docker details. It helps to replicate the environment setup that you have with all security flags and dependency. But unfortunately, still it didn't reproduce the issue.
Along with the above config, I also created the docker image with the provided details as below,
MartinLukas-oss , I am sending a script file (attachment). Can you run the script in one of your failing pods and provide me the output (0x2746-report.txt)?
collect-0x2746.sh
MartinLukas-oss commentedon Jun 9, 2026
Diagnostic approach
To reproduce reliably without fighting a crashed/CrashLoopBackOff pod, we built a thin diagnostic image on top of the exact failing application image — same base, same installed packages, no changes to the environment:
The entrypoint.sh first attempts a real mssql_python.connect(). On failure it runs the collect-0x2746.sh diagnostic collector. The Job was deployed into the same Kubernetes namespace with the same workload identity (UAMI) and service account as the failing deployment, so network path, DNS, and token acquisition are identical.
Report was collected via:
kubectl logs -n <NAMESPACE> job/sql-diag > 0x2746-report.txtKey findings from the report
Python-level TLS handshake succeeds (section C4): ssl.create_default_context() completes a TLSv1.3 / TLS_AES_256_GCM_SHA384 handshake against the server. The CA chain, cert, and Python's OpenSSL all agree.
TCP is reachable (section C3): socket.create_connection() to port 1433 succeeds in ~33ms via the private endpoint.
The ODBC driver fails (section D1): mssql_python.connect() with the exact same FQDN and Authentication=ActiveDirectoryDefault;Encrypt=yes;TrustServerCertificate=no; raises 0x2746. The failure is inside the driver, not at the OS/cert level.
No bundled libssl/libcrypto (section A6): the mssql_python wheel ships libmsodbcsql-18.5.so but no libssl* or libcrypto*. The ODBC driver therefore uses the system OpenSSL 3.5.6, which is a very recent release (April 2026). All ldd dependencies resolve (section A7 — no missing libs).
No TLS hardening (section B1): openssl.cnf has no MinProtocol, CipherString, or FIPS directives.
Attached:
0x2746-report-redacted.txt (hostnames, IPs, and namespace names have been anonymised)
subrata-ms commentedon Jun 9, 2026
Hi MartinLukas-oss, thank you for running the script and sharing the output (0x2746-report-redacted.txt). This was very helpful in collaborating on the investigation. I’ve now been able to identify the root cause and am proposing a potential fix.
RCA:
Base image: Debian 13 trixie — released after msodbcsql 18.5 and not in Microsoft's supported matrix (msodbcsql 18 supports Debian 11/12, Ubuntu 22.04/24.04, RHEL 8/9, Alpine, SUSE — not Debian 13).
System OpenSSL: 3.5.6 (April 2026) — much newer than what msodbcsql 18.5 was built/tested against.
Bundled driver file: libmsodbcsql-18.5.so.1.1. The .1.1 suffix is the OpenSSL 1.1 ABI build. There is no libssl / libcrypto in the ldd output because the driver dlopen()s OpenSSL at runtime.
On Debian 13 only libssl.so.3 exists; libssl.so.1.1 is gone from the repo. So the driver either fails to load its preferred OpenSSL or loads libssl.so.3 (5.x) through a compatibility path that misbehaves on the TLS 1.3 handshake → server resets → WSAECONNRESET = 0x2746.
0x2746 literally means "connection reset / link failure during/after the SSL handshake." Python's ssl (using libssl.so.3 directly) completes the handshake; the driver, going through its bundled
Recommended Fix
Upgrade mssql-python to latest release ( mssql-python 1.8.0 - https://pypi.org/project/mssql-python/ ) this automatically install/deploy libmsodbcsql-18.6.so.2.1 which is compatible with Debian 13 trixie. This should resolve the issue.
MartinLukas-oss commentedon Jun 9, 2026
Update: 1.8.0 appears to resolve the issue. Thank you very much!
Tested on:
Python 3.12 (Debian trixie, system OpenSSL 3.5.6) ✅
Python 3.14 (Debian trixie, system OpenSSL 3.5.6) ✅
Both previously failed with 0x2746 on 1.7.1.
Request: could the team confirm whether 1.8.0 contains an explicit fix for OpenSSL 3.5.x compatibility, and whether 1.7.1 should be yanked / marked as broken on Debian trixie?
denys-nva commentedon Jun 9, 2026
Update 1.8.0 appears to solve the issue in Microsoft Fabric as well, tested on Runtime 1.3.
Thanks!!!!!
subrata-ms commentedon Jun 10, 2026
Thanks MartinLukas-oss , denys-nva for the confirmation.
subrata-ms commentedon Jun 10, 2026
Hi MartinLukas-oss , Thanks for sharing the details. From what we can see, the behavior in your system/pod appears to be aligned with the Microsoft-supported distribution matrix for msodbcsql 18.
You can refer to the official support matrix here:
👉 Microsoft ODBC Driver System Requirements - https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/system-requirements?view=sql-server-ver17
Based on this matrix:
Let us know how you’d like to proceed—we’re happy to work together on identifying the best path forward depending on your constraints (driver version vs OS baseline).
MartinLukas-oss commentedon Jun 10, 2026
Hi Subrata (@subrata-ms) ,
I guess it works for me now.
One of the most attractive features of this project is that I do not have to install multiple package into whatever host I am currently running it on - at least I thought I don't. If the OS/Driver/OpenSSL compatibility issues rear their ugly heads again through the backdoor, I think I would be great if not only the compatible python version, but the also the compatible commonly used distributions could be documented. If versions >1.4 .0 to <1.8.0 just don't work on a commonly used distro without any (obvious?) modifications to it, I would at least appreciate a warning in the docs. (or maybe your diagnostic script to run on a local build to check for compatibility issues?).
I understand that it is not "your fault" and you have been nothing but helpful with this great project in general and this issue specfically, but I would suspect that such a warning might reduce the number of future bug reports.
Thanks again for your work!
subrata-ms commentedon Jun 10, 2026
Hi MartinLukas-oss , Thank you for the kind feedback and for highlighting this gap—your suggestion to document compatible Python versions and common distributions is very valuable.
We’ll consider adding clearer compatibility guidance and possibly a diagnostic check to help reduce confusion and prevent future issues.