Skip to main content

ArpeMSSQL — Troubleshooting

Common failures and their fixes, grouped by where they show up: connecting, authenticating, the licence gate, and querying/ingesting. For the option details referenced here, see Connection.

Connection​

Connect hangs, then fails after ~30 s. The TCP connect budget (login_timeout, default 30 s) elapsed. When a host resolves to several addresses they share that budget, so this usually means every address is unreachable — a firewall, a wrong port, or the server not listening. Verify with nc -vz <host> 1433. Lower login_timeout to fail faster while diagnosing.

A machine name is much slower than localhost / an IP. The name resolved to several addresses and a leading one (often a link-local fe80:: on Windows) is dropping the SYN. The shared connect budget prevents a flat +30 s stall, but a dead first address still costs time. Connect by IP, or fix DNS/hosts ordering.

Named instance won't connect ("Cannot resolve SQL Server instance …"). Server=host\INSTANCE needs the SQL Server Browser reachable on UDP 1434. Either open UDP 1434 and start the Browser service, or pin the instance to a static port in SQL Server Configuration Manager and connect with an explicit port (Server=host\INSTANCE,54312), which skips the Browser lookup entirely. See Named instances.

(localdb)\... fails. LocalDB is reached over a named pipe, not TCP — this driver cannot connect to it. Use a full SQL Server (Express is fine).

Azure SQL "Redirect" connection resets. The Redirect gateway policy sends the client to a database node on ports 11000–11999; the driver follows the routing token automatically, but the reconnect needs outbound TCP to 11000–11999. Open that range, or ask your admin to set the server's connection policy to Proxy.

TLS / certificates​

"unable to get local issuer certificate" on RHEL 8 or Windows. On these platforms the driver does not find the operating system's CA certificates by itself, so encrypt=true connections and Microsoft Entra ID sign-in fail certificate verification. Point it at a PEM CA bundle with the SSL_CERT_FILE environment variable — on RHEL 8: SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt; on Windows, a PEM file containing the root CAs you trust.

"certificate verify failed" / hostname mismatch. With encrypt=true the server certificate and hostname are verified by default. For a self-signed dev server, add trust_server_cert=true. Do not use trust_server_cert=true in production — fix the certificate instead. For an IP-literal host, the cert must carry a matching iPAddress SAN.

Azure SQL rejects an unencrypted connection. Azure requires TLS — set encrypt=true (the default-safe path handles SNI + verification).

Windows: driver DLL not found / fails to load. The released arpemssql_adbc_driver-win-x64.dll is self-contained (TLS and the C runtime are built in), so no OpenSSL or VC++ runtime DLLs are needed. Check that the client process is 64-bit (the DLL is x64) and that the driver manager can find the driver — see the install guide.

Authentication​

Login failed for user '…'. SQL login credentials are wrong, or the login is disabled / lacks access to the database. Confirm with sqlcmd/SSMS first.

Integrated auth on Linux: "Trusted/integrated authentication is unavailable". Integrated (trusted) authentication is available on Windows only. On Linux, use a SQL login or Microsoft Entra ID.

Integrated auth (Windows): InitializeSecurityContext: SSPI 0x… error. The Kerberos SPN usually did not match. The driver derives MSSQLSvc/host:<resolved-port> — for a named instance the port is the resolved one. Ensure the SPN is registered for the SQL Server service account, connect by FQDN, and override the SPN with adbc.arpemssql.krb5.spn if needed. Details in Authentication.

Entra ID: "Federated (access-token) authentication cannot be combined with a username/password". Remove username/password — federated (token) auth is exclusive and always uses full TLS. Also ensure encrypt=true.

Entra ID: token acquired but "login failed". The identity (user, service principal, or managed identity) must be a database user: CREATE USER [<name>] FROM EXTERNAL PROVIDER. A valid token for a principal with no database mapping still fails login.

auth_type=ActiveDirectory… rejected. Only ActiveDirectoryDefault (the credential chain) is a valid auth_type. For the other Entra modes use the dedicated options: access_token, tenant_id+client_id+client_secret, or managed_identity. See Connection.

Licence​

Connection fails with an ARROW_LIC_* error. No valid Arpeio licence was found. Supply one via arpeio.adbc.license_file (a .lic path), arpeio.adbc.license (the blob inline), the ARPEIO_ADBC_LICENCE[_FILE] environment variable, or an arpeio_adbc.lic file next to the driver library. The installer's --license flag places the file for you. Full detail — including how to read the current licence state with arpeio.adbc.license.status — is in Licensing.

Query & ingest​

Ingested rows disappear after the connection closes. With the DB-API default autocommit=False, an ingest joins your open transaction and is rolled back unless you call commit(). Commit, or open the connection with autocommit=True. See Bulk ingest an Arrow table.

adbc_ingest(mode="create") fails "already exists". The target table exists; the driver returns ALREADY_EXISTS (SQL Server error 2714). Use append, replace, or create_append.

A geospatial column reads as opaque bytes I can't parse. That is geospatial=varbinary (raw CLR-UDT bytes). Use the default geoarrow (or wkb) mode for interoperable output. See Geospatial types.

Getting the SQL Server error number. Errors raised by the server carry its error number, state, severity and message as ADBC error details (arpemssql.sqlserver.error_number, .state, .severity, .message); in Python read them from the exception's details. Clients on the ADBC 1.0 error API get the error number in vendor_code.

Cancelling a long query does nothing. Connection.Cancel / Statement.Cancel return NOT_IMPLEMENTED today — close the statement or connection to abort an in-flight query.

See also​