Skip to content
Connect > Client Libraries

Troubleshooting the Client Libraries

Symptoms, the message you see, the cause, and the fix. Error text is quoted as the library emits it.

Connection and login

JDBC login refused by server: ...

The server rejected your SQL credentials. The message carries the server's reason, for example 005-AUTHENTICATION FAILED: BAD_CREDENTIALS (wrong username or password) or ... SERVICE_DISABLED (the JDBC service is turned off on that server). Check the credentials on the JDBC configuration, and confirm the JDBC acceptor is enabled on the server.

JDBC login failed, no response: ...

The client connected but the server never answered the login. Usually the port is wrong (you reached something that is not the JDBC acceptor) or the server is not fully up. Confirm the JDBC port, remember 3280 is the only default; a Center or Relay port will accept a socket but never speak JDBC.

Unsupported JDBC server version: <v>, expected: 2

The server speaks a different JDBC protocol version than this client. Align the client and server versions.

Center/gateway login REFUSED (status=...); the server will ignore subscriptions on this connection, so no updates will arrive. Check the username/password.

Your Center subscription connected but the login was refused, so no on_update will ever fire even though subscribe returned. Fix the username/password on the Center (subscribe) configuration. This is the usual explanation for "I subscribed and nothing happens."

No login response within <n>s; proceeding without it. Subscriptions will be sent, but a gateway that requires a login will discard them.

The Center login timed out (after 10 seconds) and the client continued anyway. If the server has a gateway that requires a login, your subscriptions are silently dropped. Check connectivity and credentials to the Center port.

add_cluster timed out

You called add_cluster with sync=true (or a timeout) and a server did not respond in time. Check that every configured shard's host and port are reachable.

TLS

failed to parse ssh-rsa modulus/exponent / failed to create RSA public key from ssh-rsa data

The trusted_server_pub_file you pinned is not a valid OpenSSH ssh-rsa public key. Regenerate or re-export the server's .pub and point trusted_server_pub_file at it.

The connection is refused (BAD_CERTIFICATE), or hangs, on a secured listener

If the server listener has a keystore, it requires a client certificate; a connection without one is rejected at the handshake with a BAD_CERTIFICATE alert. Provision a client certificate and pin the server, then set trusted_server_pub_file, client_cert_file, and client_key_file on the shard's SslOptions. Full procedure: Configuration → Connecting to a secured server.

A pyami.pyjdbc client will hang here rather than error, because it opens a plain socket with no TLS and cannot complete a handshake at all. Against a secured port use the native (Python 3.14) or C++ client.

Python, DB-API and bulk operations

failed to connect to AMI server at '<host>:<port>': ...

The DB-API connect() could not reach the server. Verify host and port (DB-API defaults to 3280), and whether TLS is required.

connection is closed / cursor is closed

You used a connection or cursor after closing it. Open a new one.

number of parameters does not match / named parameters required but mapping or sequence not provided

The parameters passed to execute do not match the :name placeholders in the SQL. The DB-API uses the named paramstyle, pass a mapping whose keys match the placeholders.

executemany UPDATE requires SET clause for multiple parameter sets / executemany requires VALUES clause for multiple parameter sets

executemany only supports INSERT ... VALUES and UPDATE ... SET shapes. Restructure the statement, or loop over execute.

bulk_insert: unsupported numpy dtype / bulk_insert: column must be a list or ndarray

A column handed to sql_bulk_insert is not a supported type. Provide each column as a Python list or a numpy array of a supported dtype.

publish: expected list of (key, value) or dict / All columns must have the same row count

The object passed to publish is malformed, or a publish_dataframe / batch has columns of unequal length. Ensure every column has the same number of rows.

Behavior gotchas (not errors)

  • A subscription returns but no updates arrive. Most often the Center login was refused (see above) , check the log for the REFUSED line. Otherwise confirm the table exists and matches your filter.

  • Fields go blank after an update. An update carries only the changed columns. Merge it onto the row you already hold, keyed by the numeric id (not object_id, which is empty on subscription updates); do not replace the whole row. See Concepts → Subscriptions.

  • All rows collapse into one / merged row is empty. You are keying the merge on object_id, which is blank on subscription updates, every row lands under "". Key on id instead.

  • Updates stall after you call the client from inside a callback. The callback runs on the I/O (delivery) thread; blocking it (slow work, or a same-connection synchronous call) stops delivery. Run blocking work on your own thread. A call on a different connection (a JDBC sql() from a Center callback) returns without blocking.
  • A large result is truncated. The native client caps SQL results at 10 000 rows by default. Raise the limit or narrow the query. See Configuration → Timeouts and limits.
  • Concurrent queries interfere. Only one JDBC request at a time per cluster is supported; serialize them or use separate clusters.
  • A benign exception is logged on Center connect. On a normal Center subscription, on_log fires with level 3 and the text "Server returned an exception (Type::Throwable); see AMI server log for details". The snapshot and live updates still arrive; on this configuration the message is expected.
  • on_logged_in arrives seconds after connect. On a Center-only connection it can lag the connect by several seconds (about 10s was observed). Do not block waiting for it, pass sync=True to subscribe to wait for the subscription to be established instead.

Partly verified live (build 32437)

The connection, subscription, merge-by-id, and secured-TLS behaviors here were reproduced against a live instance. The login-refusal and parameter-error strings are quoted from source; not every one was triggered live, so the surrounding output may differ, but the wording is accurate.