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.

"Option '…' is too long (max … bytes)" / "Connection string: '…' value is too long". Since v0.4.7 a server, database, username or password longer than 255 bytes, or an ssl_root_cert path longer than 1023 bytes, is rejected instead of being cut to fit (the same applies to PGUSER, PGPASSWORD and PGSSLROOTCERT). Check the value for a stray paste.

An option value that used to load now fails with INVALID_ARGUMENT. Since v0.4.7, adbc.connection.autocommit and adbc.ingest.temporary take only true / false / 1 / 0, and the integer options (buffer_size, batch_size, max_batch_size, memory_budget_mb, arpepgsql.bulk_batch_size) reject trailing text such as 10abc; buffer_size must also be positive. Earlier versions read such values as false or as their leading digits, or ignored them.


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.

sslmode=require fails certificate verification after upgrading. Since v0.4.7, require verifies the chain when a root certificate is set (ssl_root_cert or the PGSSLROOTCERT environment variable), as libpq does. Point the root certificate at the CA that signed the server's certificate, or remove the setting if you rely on require without verification. See Authentication → TLS.

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.

"channel_binding=require, but the server requested authentication method …" / "… authenticated the client without channel binding". Since v0.4.7, channel_binding=require accepts only a SCRAM-SHA-256-PLUS login. The pg_hba.conf line matching your connection uses another method (password, md5, gss, sspi or trust). Switch that line to scram-sha-256 (with the role's password stored as SCRAM), or set 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​

"a result set is still open on this connection; read it to the end or release it first". Since v0.4.7 a connection refuses a new command while a result set from an earlier one is still being read (INVALID_STATE); earlier versions returned wrong results instead. Read the first result to the end (fetch_arrow_table(), or iterate the reader), or close its cursor or reader, before running the next statement, commit() or a metadata call.

"current transaction is aborted, commands ignored until end of transaction block" (SQLSTATE 25P02). With autocommit off, a statement failed earlier in the transaction, and PostgreSQL refuses everything after it. Call rollback(), then retry. Since v0.4.7 the driver keeps the session after a SQL error, as PostgreSQL clients do, so the transaction stays open until you end it.

Ingested rows disappear when the connection closes. Since v0.4.7, adbc_ingest with autocommit off joins the connection's open transaction: call commit() to keep the rows, as for any other statement. A rollback() undoes the ingest.

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. Temporary-table ingest 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.

"column "…": 'infinity' / '-infinity' has no Arrow … value". Arrow dates and timestamps cannot hold PostgreSQL's infinite values. Map them in the query, for example NULLIF(valid_to, 'infinity'). See Data types → Infinite dates and timestamps.

"query returned more than one result set". On the text row path (see copy_format) a query text must hold a single statement. Run the statements one at a time.

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​