Skip to main content

ArpeTeradata — Troubleshooting

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

Connection​

The connect call fails, not the first query. This is expected: the driver logs on in AdbcConnectionInit (Python's dbapi.connect()), so host, port, TLS, TTU and credential errors are all reported there.

logon requires adbc.arpeteradata.server and username. Set adbc.arpeteradata.server, and adbc.arpeteradata.username for a TD2 logon. With logmech JWT, KRB5 or TDNEGO no username is needed.

Unknown database option: …. The key is not an ArpeTeradata option. Check the spelling in the option reference.

uri: … or connection_string: … at connect. The URI or connection string could not be read: the message names the part at fault (scheme, missing host, unknown key, a field given twice, a bad port or timeout). Check it against Three ways to connect. A password containing @ : / ? # & % + must be percent-encoded in a URI. Releases before v0.3.5 ignore both keys: set the fields as discrete options.

A value in my URI has no effect. A discrete option for the same field wins over the URI or connection string, whatever the order they are set.

Teradata connection failed: TLS to <host>:443 unavailable (…); legacy port logon failed (…). With the default sslmode=prefer, the driver tried TLS on the HTTPS port, then the legacy port, and both failed. The message gives both reasons:

  • If the server has TLS, check that the HTTPS port (https_port, default 443) is reachable: nc -vz <host> 443.
  • If it has none, the legacy port needs TTU on the client (see TTU and the legacy port) and port 1025 reachable: nc -vz <host> 1025.

Teradata logon timed out after N s. The logon did not finish within login_timeout (default 60 s): usually a firewall that drops packets, a wrong port, or a stopped server. Name lookups (DNS) are not covered by this timeout.

the connection was lost after an earlier error (…); open a new connection. An earlier call on this connection hit an I/O error, for example a query_timeout read timeout, and the driver closed the socket so that a late reply cannot be mistaken for the next result. Open a new connection; raise or remove query_timeout for long queries.

A call fails after about 2 minutes on a dead network. The server or the network vanished without closing the connection; TCP keepalive detected it. Reconnect.

batch_size must be a positive integer / only UTF8 is supported for adbc.arpeteradata.charset in this version / adbc.arpeteradata.sslmode must be disable, allow, prefer, require, verify-ca or verify-full. Use one of the documented values.

TLS​

TLS certificate verification failed: …. With verify-ca or verify-full, the gateway certificate does not chain to a CA the driver trusts, or (verify-full) its name does not match the host you connect to.

  • For a certificate signed by an internal CA, give the CA with adbc.arpeteradata.sslca (PEM file) or adbc.arpeteradata.sslcapath.
  • If you set SSL_CERT_FILE / SSL_CERT_DIR, only those locations are searched: unset them or include the CA there.
  • With verify-full, connect by the name in the certificate. An IP address must be in the certificate's IP addresses.

See Where trusted certificates come from.

TLS certificate verification failed: unable to get local issuer certificate on Teradata's free trial. The trial's certificate cannot be verified from the client: use sslmode=require. See Teradata cloud environments. A certificate failure never falls back to the legacy port.

cannot load the CA certificates. The sslca / sslcapath path is wrong or not PEM.

Teradata TLS connection to <host>:443 failed: … with require, verify-ca or verify-full. The TLS port is closed, filtered or not a Teradata gateway, or the server has no TLS. These modes never fall back: check the HTTPS port, or use prefer / disable to use the legacy port (which needs TTU).

Teradata TLS logon failed: …. TLS was up, but the gateway did not accept the TLS logon (the message gives the server's code and text). The TLS logon needs Teradata 16.20.53.30 or later with a gateway certificate; on an older server, use prefer (falls back to the legacy port) or disable.

WARNING: ArpeTeradata: TLS logon without server certificate verification … on standard error. The session is encrypted, but with allow, prefer or require the certificate was not checked, so the password could be intercepted. Use verify-ca or verify-full, or set ARPETERADATA_NO_TLS_WARNING=1 to silence the warning.

TTU and the legacy port​

The legacy port (servers without TLS, sslmode=disable, or a fallback from prefer / allow) needs Teradata Tools and Utilities on the client. A TLS logon needs none.

TTU CLIv2 not found (tried: …) (INVALID_STATE). The driver found no libcliv2.so (Linux) or wincli32.dll (Windows) in its search order.

  • If the server has TLS, you don't need TTU: use sslmode=prefer (default), require or verify-full, and check that port 443 is reachable.
  • Otherwise install TTU (CLIv2 17.10 or later, plus TeraGSS), or point adbc.arpeteradata.ttu_path / ARPETERADATA_TTU_PATH at the directory that holds the library (on Linux, typically /opt/teradata/client/20.00/lib64).
  • A directory listed as (skipped: …) was refused because other users could write to it. Fix its permissions, or name it explicitly in ttu_path.

logon mechanism LDAP is not supported over TLS (sslmode=…); use sslmode=disable … (NOT_IMPLEMENTED). LDAP, and TD2 / KRB5 / TDNEGO given logdata, log on only through TTU on the legacy port. Use sslmode=disable (or prefer), or switch to JWT or Kerberos for a logon over TLS. See Authentication → LDAP.

CLIv2 has no free session slots (error 301). Logons that timed out or logoffs that failed have used up CLIv2's session slots in this process. Close the process's legacy-port connections, or restart the process.

A ttu_path change has no effect. CLIv2 is loaded once per process; a different ttu_path given later is ignored (a note is printed on standard error). Restart the process.

Logon​

Teradata logon failed: 8017 The UserId, Password or Account is invalid. (UNAUTHENTICATED). Wrong user or password, or (JWT, Kerberos) an identity the server maps to no database user. For JWT and Kerberos users, the DBA must also have granted GRANT LOGON ON ALL TO <user> WITH NULL PASSWORD;. A rejected logon never falls back to another path.

Teradata logon failed: CLIv2 error 244: … EM_SSOLOGONFAIL … (UNAUTHENTICATED). On the legacy port, the gateway refused an LDAP, JWT or Kerberos logon: wrong directory password, expired or untrusted token, or unknown user.

logmech JWT requires adbc.arpeteradata.logdata of the form token=<JWT>. Set adbc.arpeteradata.logdata to token= followed by the token.

adbc.arpeteradata.logmech must be TD2, LDAP, KRB5, TDNEGO or JWT (got '…'). Use one of these mechanism names (not case-sensitive).

A JWT logon that worked stops working. The token has expired. Get a fresh token for each connection.

Kerberos​

Teradata logon failed: Kerberos: no service ticket for TERADATA/<server>: … (UNAUTHENTICATED). The driver could not get a service ticket over TLS. Kerberos's own reason follows:

  • No ticket: run kinit user@REALM first, and set KRB5CCNAME if the ticket cache is not the default one.
  • The KDC does not know TERADATA/<server>: the principal uses the server name exactly as given, with no DNS lookup. When you connect by IP address or through a DNS alias, set adbc.arpeteradata.kerberos_spn (for example TERADATA/td.example.com@EXAMPLE.COM).

Teradata logon failed: Kerberos logon needs the GSS-API library of MIT Kerberos (libgssapi_krb5.so.2 …); not found (tried: …) (INVALID_STATE). Linux: install MIT Kerberos (krb5-libs on Red Hat, libgssapi-krb5-2 on Debian and Ubuntu), or point ARPETERADATA_GSSAPI_LIBRARY at the library.

CLIv2 error 235: … No Kerberos credentials available. A Kerberos logon on the legacy port without a ticket: run kinit.

CLIv2 error 507 (BADLOGMECH) on Debian or Ubuntu. TTU looks for the Kerberos library in the Red Hat locations only. Link it into /usr/lib64 as shown in Authentication → Kerberos.

Licence​

ArpeTeradata licence check failed [ARROW_LIC_…]: … (source: …). The driver found no valid licence, or the licence has expired or does not cover ArpeTeradata. 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​

My writes are gone after closing the connection. Closing a connection rolls back uncommitted work, and Python's dbapi.connect() turns autocommit off by default. Call conn.commit(), or connect with autocommit=True.

Commit/Rollback require autocommit to be disabled (INVALID_STATE). Commit and Rollback apply only with adbc.connection.autocommit=false.

… Teradata rolled back the open transaction. In Teradata mode with autocommit off, a failed request makes Teradata roll back the whole transaction: the work since the last Commit is lost. Redo it; the next statement opens a new transaction.

adbc.connection.autocommit must be true or false (got '…'). Only the exact values true and false are accepted.

Error 2631 (IO, SQLSTATE 40001). The transaction was aborted by a deadlock: retry it.

Query & ingest​

Error 2616 Numeric overflow occurred during computation in an aggregate. Teradata gives SUM and arithmetic on DECIMAL a result precision derived from the operands, so summing products of DECIMAL(15,2) columns over many rows can overflow. Cast an operand to a wider type, for example SUM(CAST(price AS DECIMAL(38,2)) * (1 - discount)), or CAST(qty AS BIGINT) for integers.

unsupported column type code <n> for column <name>. The result has a column type the driver does not map. Cast it in the query. See Data types → Unsupported types.

Error 6705 or 6701 on a GRAPHIC / VARGRAPHIC column. Teradata refuses to export GRAPHIC to a UTF8 session. Use TRANSLATE(col USING GRAPHIC_TO_UNICODE) in the query.

A bound SELECT fails with NOT_IMPLEMENTED. The bound rows of a parameterised SELECT must fit in one request (about 1 MB). Bind fewer rows per call.

Parameter N: … / value out of range for Teradata …. A bound column has an Arrow type the driver cannot send (dictionary, list, struct, …), or a date, time or timestamp outside Teradata's range (years 1 to 9999). See Bound parameters.

Error 5404 when binding a time or timestamp. A value with a fractional second was bound into a TIME(0) / TIMESTAMP(0) column. Round the value, or widen the column.

Strings are cut after ingest. In Teradata session mode, a string longer than its column is truncated silently; created string columns are VARCHAR(4000) by default. Raise adbc.arpeteradata.ingest.varchar_length (up to 32000), or create the table yourself and ingest with append. In ANSI mode the same case fails with error 3996.

Error 3933 at ingest create. The declared row is too wide for Teradata: lower adbc.arpeteradata.ingest.varchar_length.

ALREADY_EXISTS on ingest. create on an existing table (use append, replace or create_append), or append with a column the table does not have.

Ingest: no volatile table "…" in this session. A temporary append needs a volatile table created earlier in the same session. Use create_append.

Error 3806 on a temporary ingest. A permanent table of the same name exists in the default database, so Teradata cannot name the volatile table. Use another name.

adbc.ingest.target_catalog: Teradata has no catalog level. Use adbc.ingest.target_db_schema for the target database.

ExecutePartitions not supported / Substrait not supported. Neither is implemented: send the query as SQL text and run it with ExecuteQuery.

See also​