Skip to main content

ArpeNetezza — Troubleshooting

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

Connection​

connect() succeeds, but the first query fails. This is expected: connections open lazily, so AdbcConnectionInit does not touch the network. Host, port, TLS and login errors are reported by the first statement or metadata call, wrapped as NPS session open failed: … or nps_session_open failed: ….

getaddrinfo(<host>:<port>): …. The host name does not resolve. Check adbc.arpenz.server. IBM Cloud NPS host names stop resolving while the instance is stopped.

connect(<host>:<port>) failed: …, or a connect that hangs, then fails. Nothing accepted the TCP connection within login_timeout (default 30 s): usually a firewall, a wrong port, or a stopped server. Netezza listens on 5480 by default. Verify with nc -vz <host> 5480.

recv timed out after N s. A read took longer than socket_timeout. Raise it, or set it to 0 (no limit) for long-running queries.

connection closed by peer. The server dropped the connection, for example after a server-side timeout or a restart. Reconnect.

Unsupported uri scheme. The uri must start with netezza://, postgresql:// or postgres:// (or the older arpenz://). For an ADO.NET Key=Value;… string, use adbc.arpenz.connection_string instead of uri.

unknown keyword '…' in a connection string. The connection string has no Port, sslmode or tls_min_version keyword. Put the port in Server (Server=nzhost,5480), and set the TLS options as discrete options or uri parameters. See Connection string.

Unknown database option: …. The key is not an ArpeNetezza option. The PostgreSQL-only options copy_format, geospatial, uuid_casing and arpenz.bulk_* were removed in v0.3.0.

TLS​

TLS handshake failed: the server only offers a TLS version older than the allowed minimum (TLS 1.2); Netezza 7.x servers stop at TLS 1.1: set adbc.arpenz.tls_min_version=1.0 (or 1.1). An NPS 7 server with sslmode=require or stricter. Set adbc.arpenz.tls_min_version=1.0 (since v0.3.2). Encrypted NPS 7 connections are not yet validated: if the handshake still fails, use sslmode=disable on a trusted network. See Authentication → NPS 7.

certificate verification failed: unable to get local issuer certificate. The server certificate does not chain to a CA the driver can find. On RHEL and Windows the driver finds no CAs unless you give ssl_root_cert (see Where trusted certificates come from). IBM Cloud NPS also does not send its intermediate certificate: put the intermediate and the root in the PEM file given as ssl_root_cert. See Authentication.

certificate verification failed: … IP address mismatch / host name mismatch. verify-full checks the name you connect to. Connect by the DNS name in the certificate, not by IP address.

could not load CA file '…'. The ssl_root_cert path is wrong or not a PEM file.

the server only accepts TLS connections; use sslmode=require, verify-ca or verify-full instead of sslmode=disable. The server requires TLS. Remove sslmode=disable.

server does not support TLS but securityLevel=onlySecured. You asked for require or stricter, and the server has TLS turned off. Enable TLS on the server, or use prefer / disable on a trusted network.

Invalid tls_min_version '…' (expected 1.0 / 1.1 / 1.2 / 1.3). Use one of those values (a TLS / TLSv prefix is accepted).

Authentication​

integrated/trusted authentication (Kerberos, SSPI) is not supported for Netezza yet; connect with a username and password. An integrated-auth option is set (trusted, auth_type=integrated, Integrated Security, Authenticator=krb5). Remove it and supply a username and password.

refusing to send the password: the connection is not encrypted and require_password_encryption is on (use sslmode=require or stronger). require_password_encryption=true and the session is not encrypted, for example because the server declined TLS under prefer. Use sslmode=require or stricter.

Access denied due to too many unsuccessful login attempts. The server locked the account. An administrator must unlock it. Check the password before retrying.

channel_binding=require cannot be satisfied: Netezza never uses SCRAM authentication / gssencmode=require is not supported: Netezza has no GSS transport encryption. These options come from PostgreSQL strings and cannot work against Netezza. Remove them; use sslmode to encrypt.

Licence​

ArpeNetezza licence check failed [ARROW_LIC_…]: … (source: …). The driver found no valid licence, or the licence has expired or does not cover ArpeNetezza. Since v0.3.4 the check runs at AdbcDatabaseInit and again at every AdbcConnectionInit. See Licensing for where the driver looks and how to read arpeio.adbc.license.status.

AdbcDatabaseInit has not succeeded on this database. A connection was opened on a database whose initialisation failed (often the licence check). Fix the first error.

Transactions​

The transaction was rolled back by an earlier error and its uncommitted changes were lost; call rollback() to continue. With autocommit off, an error inside a transaction makes Netezza discard the whole transaction. Later statements would be silently ignored, so the driver refuses them, and Commit, until you call Rollback. Then redo the work.

Cannot commit: connection is in autocommit mode. Commit and Rollback apply only with adbc.connection.autocommit=false.

Query & ingest​

NzType N … not yet supported. The result has a column type the driver cannot decode yet. Fixed-length BINARY is the known case; cast it to VARBINARY in the query. See Data types.

Bulk ingest requested but no data was bound to the statement. Ingest reads its data from BindStream, not from Bind. Bind a stream (Python's adbc_ingest does this for you), and set both adbc.ingest.target_table and adbc.ingest.mode.

BindStream without a bulk-ingest target is not supported on the native NPS path. BindStream is only for ingest. To run a statement once per parameter row, use Bind with a batch.

ingest: unsupported Arrow type '…' (column N "…"). The column's Arrow type cannot be ingested (unsigned integers, view types, decimals other than decimal128, …). Cast it first; see Accepted Arrow types.

ingest_method=external: the external-table load cannot express this ingest (…). With ingest_method=external, the fallback to INSERT is turned off. The message gives the reason (a column name that does not match the target, an unsupported type pair, a row over 64 KiB, …). Fix that, or use ingest_method=auto.

An ingest is very slow (a few rows per second). It fell back to the batched INSERT path. Set ARPEIO_ADBC_WRITE_TIMING=1 to see path=insert-union in the [NZ INGEST SUMMARY] line on standard error. Then check the fallback conditions; a column whose name differs from the target column is the usual cause.

temporary ingest requires a reusable native session (server, username, and password). adbc.ingest.temporary=true needs a username and password on the connection.

Bound-parameter execution requires all Arrow columns to map to a supported NPS RPC type. A bound column's Arrow type cannot be rendered (uint32, uint64, date64, intervals). See Bound parameters.

Partitioned execution not supported / Substrait not supported. Neither is implemented. For parallel reads, open one connection per worker and split the query yourself.

A created table has SMALLINT where you expected BYTEINT, or an NVARCHAR narrower than your data. create mode maps int8 to SMALLINT and shares the 64 KiB row budget across string columns. Create the table yourself and ingest with append. See Data types.

Diagnostics​

Environment variableEffect
ARPEIO_ADBC_READ_TIMING=1Per-batch [NPS READ] timing lines and a summary on standard error.
ARPEIO_ADBC_WRITE_TIMING=1An [NZ INGEST SUMMARY] line per ingest (rows, path, timings) on standard error.
ARPEIO_ADBC_ALLOCATOR=system / mimallocChooses the memory allocator.

See also​