Troubleshooting

Troubleshooting

1. How do I fix a "Connection refused" error from SQL Server?

Check if TCP/IP is enabled.

Open SQL Server Configuration Manager. Under SQL Server Network Configuration, enable TCP/IP and activate the IP used for the connection in TCP/IP Properties.

2. How do I fix an "ODBC Driver for SQL Server: file not found" error?

This error applies to the default pyodbc path. Install Microsoft ODBC Driver 18 or 17 for SQL Server. When the driver option is omitted, mssql-django tries Driver 18 first and automatically falls back to Driver 17. If multiple versions are installed, specify the driver name or path in settings.py:

DATABASES = {
    "default": {
        ...
        "OPTIONS": {
            "driver": "/location/to/libmsodbcsql-17.0.so.2.1",
        },
    }
}

The mssql-python path uses Microsoft ODBC Driver 18 from the automatically installed mssql-python-odbc companion package. It ignores the driver option and does not fall back to Driver 17.

3. Why does mssql-python reject an extra_params option that works with pyodbc?

mssql-python 1.15 validates connection-string parameters against a strict allowlist. Supported options include Authentication, Encrypt, TrustServerCertificate, HostnameInCertificate, ServerCertificate, ServerSPN, MultiSubnetFailover, ApplicationIntent, ConnectRetryCount, ConnectRetryInterval, KeepAlive, KeepAliveInterval, IpAddressPreference, and PacketSize.

pyodbc-only options such as APP, LongAsMax, ColumnEncryption, WSID, Connect Timeout, MARS_Connection, DRIVER, and DSN must be removed before selecting mssql-python. Use the Django connection_timeout option instead of Connect Timeout. Always Encrypted configurations using ColumnEncryption must remain on pyodbc.

See Selecting the database driver for the complete compatibility notes.