Editéieren

Troubleshoot mssql-python

Use this article to find troubleshooting guidance for the mssql-python driver. Start with the symptom or error message that matches your issue.

Install issues

pip install fails or builds from source

For unsupported Python versions, missing wheels, inactive virtual environments, and missing Linux libraries, see Troubleshoot installation and connection issues.

Conflicting driver installations

For import errors or unexpected behavior when mssql-python and pyodbc are installed together, see Troubleshoot installation and connection issues.

Connection issues

Unable to connect to server

For SQLSTATE 08001, unreachable servers, stopped services, and Azure SQL firewall rules, see Troubleshoot installation and connection issues.

Login failed

For SQLSTATE 28000, authentication mode mismatches, invalid credentials, and missing database users, see Troubleshoot installation and connection issues.

Connection timeout

For SQLSTATE HYT00 or HYT01, network latency, slow servers, and connection timeout settings, see Troubleshoot installation and connection issues.

SSL certificate errors

For untrusted certificate errors and safe local development options, see Troubleshoot installation and connection issues.

Query execution issues

Table or object not found

For SQLSTATE 42S02, database context, schema qualification, and table existence checks, see Troubleshoot query, data, and operation issues.

Syntax error

For SQLSTATE 42000, SQL syntax, string escaping, and parameterized queries, see Troubleshoot query, data, and operation issues.

Parameter errors

For SQLSTATE 07001, placeholder counts, and supported parameter styles, see Troubleshoot query, data, and operation issues.

Data type issues

Datetime conversion errors

For SQLSTATE 22007 and datetime parameter conversion, see Troubleshoot query, data, and operation issues.

Decimal precision issues

For truncated or rounded decimal values, see Troubleshoot query, data, and operation issues.

Unicode encoding issues

For garbled special characters and Unicode column types, see Troubleshoot query, data, and operation issues.

Performance issues

Slow query execution

For indexing, large result sets, and connection pooling, see Troubleshoot query, data, and operation issues.

Memory issues with large results

For streaming and paginating large result sets, see Troubleshoot query, data, and operation issues.

Transaction issues

Temp table scoping with autocommit

For temp tables that disappear after rollback and DDL statements that require autocommit, see Troubleshoot query, data, and operation issues.

Transaction not committed

For data changes that don't persist after the connection closes, see Troubleshoot query, data, and operation issues.

Deadlock errors

For SQLSTATE 40001, retry guidance, and recurring deadlock analysis, see Troubleshoot query, data, and operation issues.

Bulk load issues

Constraint violations during bulkcopy

For primary key, unique, check, or foreign key violations during bulk copy, see Troubleshoot query, data, and operation issues.

Column mapping errors

For bulk copy column count and column order mismatches, see Troubleshoot query, data, and operation issues.

Type mismatches during bulkcopy

For truncated, rounded, or incorrect values after bulk copy, see Troubleshoot query, data, and operation issues.

NumPy type binding failures

For parameter binding failures with NumPy integer or float types, see Troubleshoot query, data, and operation issues.

Bulkcopy with temp tables

For Invalid object name errors when you use bulkcopy() with a session temp table, see Troubleshoot query, data, and operation issues.

Container and CI issues

Missing system libraries on Linux

For missing libltdl or Kerberos libraries in Linux environments, see Troubleshoot installation and connection issues.

macOS SSL errors after install

For SSL-related errors on macOS, including Apple silicon, see Troubleshoot installation and connection issues.

Diagnostic tools

Enable driver logging

Use mssql_python.setup_logging() to enable DEBUG logging. The driver logs SQL statements, parameters, internal ODBC operations, and connection state changes.

import mssql_python

# Enable logging to file (default)
mssql_python.setup_logging()

# Output to stdout (useful for CI/CD and containers)
mssql_python.setup_logging(output="stdout")

# Output to both file and stdout
mssql_python.setup_logging(output="both")

# Custom log file path (must use .txt, .log, or .csv extension)
mssql_python.setup_logging(log_file_path="/var/log/myapp/mssql.log")

Log files use CSV format and rotate automatically at 512 MB with five backups. The driver sanitizes sensitive data such as passwords and access tokens in log output.

To add application entries to the driver log, use driver_logger:

import mssql_python
from mssql_python.logging import driver_logger

mssql_python.setup_logging()

driver_logger.debug("[App] Starting data processing")
driver_logger.error("[App] Failed to process record")

Caution

Logging has performance overhead. Enable it only when you troubleshoot an issue. Don't enable it in production by default.

Get driver information

Retrieve the driver version and server details from an active connection:

import mssql_python

conn = mssql_python.connect(connection_string)

print(f"Version: {mssql_python.__version__}")
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

Check connection state

Run a lightweight query to test whether a connection is still open:

import mssql_python

try:
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    print("Connection is open")
except mssql_python.Error:
    print("Connection is closed or broken")

Quick reference: Common errors

Error SQLSTATE Common cause Troubleshooting
Client unable to establish connection 08001 Server unreachable Unable to connect to server
Login failed 28000 Incorrect credentials Login failed
Timeout expired HYT00 or HYT01 Slow network Connection timeout
Invalid object name 42S02 Incorrect table or schema Table or object not found
Syntax error 42000 SQL error Syntax error
Constraint violation 23000 Foreign key or primary key violation Constraint violations during bulkcopy
Deadlock 40001 Lock contention Deadlock errors

Related content

  • Last updated on