Troubleshooting

Troubleshooting

Home / Solve a problem

Start with the failing phase and one observable symptom. The entries below are diagnostic leads, not proof that every matching error has the same cause.

For the full diagnostic workflow, use the SqlClient troubleshooting guide on Microsoft Learn. This wiki's symptom table adds migration-specific routes.

Find your symptom

Error or symptom	Check first	Continue
Certificate chain not trusted / certificate name mismatch	Server certificate, issuing chain in the client trust store, expected hostname, explicit encryption settings	Security
Pre-login TLS handshake failure	Certificate errors, network path, server patch level, OS TLS policy; do not infer a single cause from "error 31"	Security
Certificate-file mismatch after a servicing update	Correct pin file, deployed path/permissions, certificate rotation; 6.1.7/7.0.3 enforce managed-SNI matching	Security
Cannot find an Entra authentication provider in 7.x	Azure extension reference and publish output for driver-provided modes	Authentication
Cannot generate SSPI context / SPNEGO failure	Identity, DNS, SPN, realm, tickets, host libraries, and server configuration	Deployment
Keyword not supported	Obsolete Asynchronous Processing; framework-specific TNIR setting; mixed SDS/MDS parsers	Code and runtime
MissingMethodException involving set_Encrypt(Boolean)	A dependency compiled against the old MDS property signature	Code
Type/assembly load failure	Package graph, affected provider assemblies, binding configuration, runtime assets	Deployment
Globalization-invariant mode not supported	Runtime settings and globalization libraries in the deployed image	Deployment
Native SNI DLL cannot load on Windows	Process architecture, complete publish output, native dependency requirements	Deployment
InvalidCastException for a nullable rowversion result	DBNull handling before reading byte[]	Runtime
Decimal values differ at the last digit	Parameter precision/scale and rounding expectations	Runtime
Pool timeout or load-related latency	Undisposed resources, long-running work, server blocking, concurrency, network time, mixed-provider pools	Feature guides
SQLCLR Context Connection=true fails	In-process context connections are not a drop-in MDS scenario	Migration planning

For TLS negotiation issues, prefer supported server/OS updates and a correct certificate configuration. Do not weaken system-wide OpenSSL policy as a generic troubleshooting step.

The existing Known Issues page remains available. It contains a historical performance-issue pointer, not a complete current issue inventory; check the linked issue's status and affected versions before applying advice.

Capture a useful report

Record the exact package version, runtime, OS/architecture, SQL Server version, authentication mechanism, failing API, sync/async mode, exception chain, and whether the issue occurs in published output.

Use event source tracing for detailed driver events and diagnostic counters for connection and pooling metrics.

Include a minimal reproduction, expected/actual results, and relevant timing or diagnostics. Preserve useful correlation IDs where your data policy permits. Remove credentials, tokens, customer data, sensitive query values, and identifying connection details before sharing logs or traces.

Search existing issues for the symptom and version, then use the issue templates. A previously reported issue is not evidence that its old workaround applies to your installed patch.

Security vulnerability? Report privately to MSRC.

Sources: SqlClient troubleshooting guide, official documentation and release notes linked from the destination pages.