Skip to main content

ArpeOracle — Troubleshooting

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

Connection​

Connect hangs, then fails. Every candidate address was unreachable within login_timeout — usually a firewall, a wrong port, or the listener not running. Verify with nc -vz <host> 1521. Lower login_timeout to fail faster while diagnosing.

"specify either 'SID' or 'Service Name', not both". A sid and a service_name select different CONNECT_DATA forms on the wire, so they cannot be combined. Pick one. In a uri, that also means a path segment (service name) plus ?sid= is rejected.

EZConnect with an IPv6 address is rejected. A bare IPv6 literal in a Server descriptor has ambiguous colons. Give the host and Port as separate keywords, or use the bracketed [::1] form in a uri.

Connecting to ADB hangs / the listener drops the connection. ADB's connect descriptor is long and needs v0.2.0 or later — upgrade. Also confirm you are using a wallet service name (<svc>_low.adb.oraclecloud.com) on port 1522 with ssl_mode=verify-full.

"… (Oracle 11g or older), which ArpeOracle does not support; a server running Oracle 12.1 or later is required". ArpeOracle speaks the 12c+ protocol layout, so Oracle 11g and older are refused at connect. There is no workaround — use Oracle 12.1 or later. See Compatibility.

Queries fail on describe against Oracle 21c / 23ai / 26ai. Upgrade to v0.2.10 or later: 12c through 26ai are all validated on current releases — see Compatibility.

TNS alias 'X' not found in <file>. A bare Server / Data Source name with no service name or SID is looked up in tnsnames.ora (since v0.3.11), and the file that was found has no such entry. Check the name (including any domain suffix, e.g. SALESDB.WORLD: sqlnet.ora's NAMES.DEFAULT_DOMAIN is not applied) and which file was read: adbc.arpeoracle.tns_admin, else $TNS_ADMIN, else $ORACLE_HOME/network/admin. See TNS alias.

Windows: parallel exports fail with cannot resolve '<host>': WSANOTINITIALISED. Opening many AdbcDatabase handles at once (FastBCP's parallel methods, one per chunk) could race Winsock startup. Fixed in v0.3.10: upgrade. Serial connections were not affected.

TLS / wallets​

"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 CA bundle (or use a wallet), or set the SSL_CERT_FILE environment variable — on RHEL 8: /etc/pki/tls/certs/ca-bundle.crt.

The connection is plaintext when I expected encryption. ssl_mode defaults to disable, and the default NNE stance accepted only encrypts when the server asks for it (REQUESTED/REQUIRED). Set ssl_mode=require/verify-ca/verify-full, or encryption=requested/required for Native Network Encryption. O5LOGON keeps the password off the wire either way, but SQL text and data are in clear until you encrypt.

"wallet_location/ssl_root_cert were given but ssl_mode is 'disable'". A wallet or CA bundle does not turn TLS on by itself. Set ssl_mode to require, verify-ca or verify-full as well.

"certificate verify failed" / hostname mismatch. With verify-ca/verify-full the certificate chain (and, for verify-full, the hostname) is checked against ssl_root_cert, else the wallet's CAs, else OpenSSL's default locations (see Authentication → TLS). Point ssl_root_cert at the right CA bundle, or use a wallet.

The wallet won't load. ArpeOracle reads ewallet.pem (client key + cert + CAs in one PEM), the python-oracledb-thin layout — not Oracle's cwallet.sso. Convert an SSO wallet with orapki wallet pkcs12_to_pem -wallet <dir>. An encrypted key needs wallet_password.

Windows: the DLL fails to load. The released arpeoracle_adbc_driver-win-x64.dll is self-contained — OpenSSL and the C runtime are included, so no extra DLLs are needed. It is a 64-bit (x64) library: the host process must be 64-bit too.

Native Network Encryption​

"server requires Oracle native network encryption … are 'rejected'". The server is set to REQUIRED and the client opted out with encryption=rejected / data_integrity=rejected. Leave them unset (accepted, the default, negotiates whatever the server asks for), or use TCPS.

"server requires Oracle native network encryption / data integrity on top of TCPS". Over TCPS an accepted stance is not advertised (the transport is already encrypted), but this server still requires NNE. Set encryption=requested/required (or data_integrity) to negotiate it inside TLS.

"… but its ACCEPT disables advanced negotiation". The server says it requires NNE yet its answer blocks the negotiation — typically a Connection Manager or proxy rewriting the connect flags. The driver refuses to continue in plaintext; fix the intermediary's configuration or connect to the listener directly.

ORA-12660 (parameters incompatible). One side requires a service the other rejects — e.g. encryption=required against a REJECTED server, or encryption=rejected against a REQUIRED server. Align the stances.

encryption=required fails the connect / ORA-12650. The server declined to negotiate a cipher ArpeOracle offers. ArpeOracle offers only AES-256 with SHA-256/SHA-1 integrity; a server that requires DES/3DES/RC4 or MD5 will not connect. Adjust SQLNET.ENCRYPTION_TYPES_SERVER / CRYPTO_CHECKSUM_TYPES_SERVER to include AES256 / SHA256 (or SHA1).

"server requires Oracle native network encryption" with default options. Before v0.3.8 the default accepted stance did not advertise NNE at all, so a server set to REQUIRED refused a default client. Since v0.3.8 accepted advertises encryption and integrity and lets the server decide, like ODP.NET and OCI — upgrade, or set encryption=required explicitly. See the client × server matrix in Connection.

Connects are slower, or bulk exports lost throughput, after upgrading to v0.3.8. With the default accepted stance every plain-TCP connection now makes one extra ANO round trip at connect, and a server set to REQUESTED now gets an AES-256 + checksum session. If you do not want NNE, set both encryption=rejected and data_integrity=rejected to restore the plain handshake with no extra round trip.

Data decodes as garbage / the stream desyncs mid-result over NNE. Fixed in v0.1.7 (SHA-1 integrity); since v0.1.6 DISABLE_OOB=ON is no longer required. Upgrade to v0.1.7 or later.

Authentication​

"ORA-01017: invalid username/password". Credentials are wrong, or — for token auth on ADB — the server-side setup is off. For OAuth2/Entra, the Application ID URI must be a domain-qualified https:// URI; the Azure default api://<appId> makes ADB reject otherwise-valid tokens with a generic ORA-01017.

OCI IAM / OAuth2 token: "login failed" though the token is valid. The Oracle identity must be mapped to a schema — IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=…' (OCI) or the Entra global-user mapping. Tokens also expire (~1 h); re-mint with oci iam db-token get or refresh the Entra token. ADB requires the wallet (mutual TLS) alongside the token.

Proxy auth fails with ORA-01017. Either the authenticating account's password is wrong, or the target has not granted the proxy: ALTER USER target GRANT CONNECT THROUGH proxyacct;. Inside the session SESSION_USER is the target and PROXY_USER the authenticating account.

Licence​

Connection fails with an ARROW_LIC_* error. The licence gate is always enforced — a driver with no valid token refuses to connect. 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. Full detail — including how to read the current licence state with arpeio.adbc.license.status — is in Licensing.

Query & ingest​

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

An ingested table "does not exist" when queried. Ingest quotes the table and column names exactly as given, so my_table becomes the case-sensitive "my_table". Query it quoted, or ingest with an upper-case name. See Data types.

A query fails with "… is not supported by this driver yet". The result has a column type ArpeOracle does not decode (e.g. BFILE, or an object type other than SDO_GEOMETRY). Leave it out of the select list, or convert it in SQL. See Data types.

Ingest into a different catalog is rejected. An Oracle session reaches one catalog only; adbc.ingest.target_catalog must be the connected service (or unset). Use target_db_schema to target a schema.

A NUMBER column comes back as strings. That is the lossless default — unconstrained NUMBER maps to utf8. For float64 or a fixed decimal, set number_mapping=double or decimal:P,S. See Data types.

Cancelling a long query. Statement.Cancel / Connection.Cancel send an in-band TNS break from another thread and work over plaintext, Native Network Encryption, and TCPS (TLS was closed in v0.2.1). The session is poisoned after a cancel and transparently reconnects on the next statement.

See also​