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
- Connection · Authentication · Licensing
- Compatibility — is your target actually supported?