Skip to main content

ArpePGSQL — Troubleshooting

Common failures and their fixes, grouped by where they show up: connecting, TLS/certificates, 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 — usually the host/port is unreachable: a firewall, a wrong port, or the server not listening. Verify with nc -vz <host> 5432. Lower login_timeout to fail faster while diagnosing.

A query hangs indefinitely and never times out. socket_timeout defaults to 0 (no per-I/O timeout). Set adbc.arpepgsql.socket_timeout to a bound in seconds to abort a stalled recv/send. query_timeout bounds a single query.

"the database system is starting up" / "too many connections". These come straight from PostgreSQL. Wait for recovery to finish, or raise max_connections / use a pooler. Not a driver issue.

Wrong database or "database does not exist". A connection sees exactly one database (no cross-catalog). Set adbc.arpepgsql.database (or the URI path segment) to the right one; SET search_path selects the schema within it.

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 verify-ca / verify-full fail unless a CA is given. Set ssl_root_cert to the PEM root CA, or set the SSL_CERT_FILE environment variable to a CA bundle — on RHEL 8: /etc/pki/tls/certs/ca-bundle.crt.

"certificate verify failed" / hostname mismatch. With sslmode=verify-ca/verify-full the server certificate chain (and, for verify-full, the hostname) is verified. Point ssl_root_cert at the PEM root CA that signed the server certificate, or fix the certificate. Do not drop to sslmode=require in production to hide a bad certificate — require encrypts but verifies nothing.

Connection silently went plaintext. The default sslmode=prefer falls back to plaintext when the server answers the SSLRequest with N, and that reply is unauthenticated (read before TLS). Over an untrusted network use sslmode=verify-full and/or channel_binding=require. See Connection → TLS & sslmode.

channel_binding=require fails. Channel binding needs a TLS channel — it is unavailable under sslmode=disable. Enable TLS (sslmode=require+), or drop channel_binding to prefer.

Windows: "DLL not found" / the driver does not load. The released arpepgsql_adbc_driver-win-x64.dll is self-contained — it needs no separate OpenSSL or Visual C++ runtime DLLs. A load failure usually means the driver manager cannot find the driver: check that it was installed (see the install guide) or load it by its full path.

Authentication​

"password authentication failed for user '…'". SCRAM/MD5/cleartext credentials are wrong, or pg_hba.conf does not permit this user/host/method. Confirm with psql first, and check the pg_hba.conf line that matches your client address. When no password option is given, the driver takes it from PGPASSWORD, then from the password file (PGPASSFILE or ~/.pgpass), since v0.4.5: a stale entry there is a common cause, and on Linux a ~/.pgpass that is readable by group or others is ignored (chmod 0600 ~/.pgpass).

"no pg_hba.conf entry for host … , SSL off". The server requires TLS (hostssl) for your address. Set sslmode=require (or verify-full).

Integrated auth on Linux: "Trusted/integrated authentication is unavailable". Integrated (trusted) authentication is supported by the Windows driver only. On Linux, use a password-family method (SCRAM-SHA-256) over TLS: remove auth_type=integrated / trusted=true (or Integrated Security=SSPI in a connection string) and supply username / password.

"server requires GSS/SSPI authentication; set auth_mode=integrated". The pg_hba.conf line matching your connection uses gss or sspi. On Windows, set adbc.arpepgsql.auth_type=integrated; on Linux, ask for a password-based pg_hba.conf entry for your role.

Windows integrated auth: "integrated auth init: InitializeSecurityContext: SSPI 0x…". Windows could not obtain a ticket for the server. The driver targets the SPN POSTGRES/<server>, built from the server value as given: connect by the fully qualified host name under which the SPN is registered (not an IP address or alias), check the registration with setspn -Q POSTGRES/<host>, and override the target with krbsrvname (service part) or krb5.spn (whole SPN) if it is registered differently. Details in Authentication.

Windows integrated auth: "server did not provide mutual authentication". Mutual auth is always enforced — the driver refuses a login in which the server was not authenticated. It typically means Kerberos was not used; fix the SPN as above. A related error, "server sent AuthenticationOk before the GSS exchange completed", means the server skipped the end of the exchange: treat it as a real security signal, not a driver bug.

Windows integrated auth: the login is rejected for the role. The server checks that your Windows identity may use the requested username. Align the role name with the account (for example include_realm=0 in pg_hba.conf) or add a pg_ident.conf map.

auth_type=ActiveDirectory… / a certificate auth mode is rejected. ArpePGSQL supports only sql and integrated/sspi; it is the driver and cannot delegate Entra ID / certificate auth to a client library.

Licence​

Connection fails with an ARROW_LIC_* error. No valid Arpeio licence was found. The gate is always enforced — there is no off switch. Supply a licence 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​

Bulk ingest hangs or the transaction never commits. Open the connection with autocommit=True for the single-connection TRUNCATE+adbc_ingest pattern; a manual transaction must be committed explicitly.

adbc_ingest(mode="create") fails "already exists". The target table exists; use append, replace, or create_append.

Ingesting utf8 into a jsonb / inet / uuid column fails, but only for a temp table. The temp-table same-session fast path keeps Arrow-only type inference (no OID transforms), so the server rejects a utf8 bound into a non-text column. Ingest into a persistent table (the OID-introspecting path), or cast in SQL afterwards. See Data types → Write path.

A geospatial column reads as opaque bytes I can't parse. That is geospatial=binary (raw EWKB, no extension metadata). Use the default geoarrow.wkb (or wkb) mode for interoperable output. See Data types → Geospatial.

Cancelling a long query. AdbcConnectionCancel / AdbcStatementCancel are implemented via an out-of-band PostgreSQL CancelRequest — cancellation works. If it does not take effect, the server may already have finished producing rows.

See also​