Errors

Python

xqdb defines three exception classes. All three derive directly from Exception and are not subclasses of each other. In particular, except xqdb.XqdbError does not catch an I/O or authentication failure.

Exception	Raised for
xqdb.XqdbIOError	Connection refused or reset, name resolution failures, socket timeouts, TLS handshake and certificate failures, and calls that need an open socket when there is none (Not Connected.). Also raised by read_binary6 for a missing file.
xqdb.XqdbAuthError	The server closed the connection during the handshake, which is how q rejects credentials. The message is Wrong credential.
xqdb.XqdbError	q errors (Internal Server Error - "<q error>"), values xqdb cannot decode or encode, text that is not valid UTF-8 under symbol_encoding="strict", invalid XqdbQOperator or XqdbQLambda arguments, and files that are not tables

Standard Python exceptions cover argument problems:

Exception	Raised for
ValueError	An unknown backend or symbol_encoding, a temporal atom with digits below a microsecond, a time argument that is not whole milliseconds, an unknown msg_type, values nested more than 64 levels deep, and cyclic containers
TypeError	More than eight query arguments, lazy frames, unsupported Python types, dictionary keys that are not str, and a non-int timeout
OverflowError	Integers outside the signed 64-bit range, temporal values outside the q or Python range, and a port above 65535
ModuleNotFoundError	A backend whose package is not installed
RuntimeError	Already borrowed, when a second thread calls a Q that another thread is using

Catch the xqdb classes together, or one at a time from most to least specific:

import xqdb

conn = xqdb.Q("localhost", 1800, timeout=10)
try:
    result = conn.sync("select from trade")
except xqdb.XqdbAuthError:
    raise SystemExit("check the q username and password")
except xqdb.XqdbIOError as error:
    print(f"connection problem, safe to reconnect: {error}")
except xqdb.XqdbError as error:
    print(f"q or conversion error: {error}")

Node.js

Every error from a call is an XqdbError or one of its subclasses. Each has three properties:

• code: a stable string, listed below.
• nativeMessage: the original message from the native layer.
• cause: the native payload, or the exception that was caught.

Class	code	Raised for
XqdbIOError	XQDB_IO	Connection, socket, timeout, and TLS failures, calls without an open socket, and file read errors
XqdbIOError	XQDB_NATIVE_LOAD	The native addon could not be loaded. The message explains how to fix it.
XqdbAuthError	XQDB_AUTH	The server rejected the credentials
XqdbError	XQDB_SERVER	q returned an error, such as 'type
XqdbError	XQDB_CONVERSION	A value could not be converted in either direction. Examples are invalid UTF-8 under the strict policy, more than eight arguments, oversized or too deeply nested arguments, unsupported JavaScript values, invalid operators or lambdas, and UNC paths passed to readBinary6.
XqdbError	XQDB_UNSUPPORTED	q types or forms that 0.1.8 cannot decode, such as month lists, negative time atoms, and big-endian messages
XqdbError	XQDB_ERROR	Other errors from the core, such as Not a table
XqdbError	XQDB_INTERNAL	The connection's worker thread stopped or panicked
XqdbError	XQDB_BACKPRESSURE	The connection already had eight commands waiting. See Node.js Workers and Backpressure.

Invalid options, such as a timeout of 0, a port outside 1 to 65535, a negative retries, or an unknown symbolEncoding, throw a RangeError synchronously from new Q() or Q.connect(). readBinary6() rejects with a RangeError for an unknown symbolEncoding.

XqdbIOError and XqdbAuthError extend XqdbError, so check them first:

import { Q, XqdbAuthError, XqdbError, XqdbIOError } from "@xbbg/xqdb";

const q = new Q({ host: "localhost", port: 1800 });
try {
  console.log(await q.sync("select from trade"));
} catch (error) {
  if (error instanceof XqdbAuthError) {
    console.error("check the q username and password");
  } else if (error instanceof XqdbIOError) {
    console.error(`connection problem (${error.code}): ${error.nativeMessage}`);
  } else if (error instanceof XqdbError) {
    console.error(`${error.code}: ${error.nativeMessage}`);
  } else {
    throw error;
  }
} finally {
  await q.disconnect();
}