Types and Exceptions

Types and Exceptions#

2026-03-31

4 min read time

Applies to Linux

This page provides references for the types and exception classes in the ucxx Python package.

Types#

class ucxx.types.Tag#

Exceptions#

The ucxx.exceptions module provides Python exception classes that correspond to UCX error codes.

exception ucxx.exceptions.UCXAlreadyExistsError#: Raised when a resource already exists.

exception ucxx.exceptions.UCXBufferTooSmallError#: Raised when a buffer is too small for the requested operation.

exception ucxx.exceptions.UCXBusyError#: Raised when a resource is busy and cannot process the request.

exception ucxx.exceptions.UCXCanceled#: Raised when a UCX operation is canceled (legacy alias for UCXCanceledError).

exception ucxx.exceptions.UCXCanceledError#: Raised when a UCX operation is canceled.

exception ucxx.exceptions.UCXCloseError#: Raised when an endpoint or connection is closed.

exception ucxx.exceptions.UCXConfigError#: Raised when there is a UCX configuration error.

exception ucxx.exceptions.UCXConnectionResetError#: Raised when a connection is reset by the remote peer.

exception ucxx.exceptions.UCXEndpointTimeoutError#: Raised when an endpoint operation times out.

exception ucxx.exceptions.UCXError#: Base exception for all UCX errors.

exception ucxx.exceptions.UCXExceedsLimitError#: Raised when a request exceeds a configured limit.

exception ucxx.exceptions.UCXFirstEndpointFailureError#: Raised on the first endpoint failure in a connection.

exception ucxx.exceptions.UCXFirstLinkFailureError#: Raised on the first link failure in a connection.

exception ucxx.exceptions.UCXIOError#: Raised when an I/O error occurs during a UCX operation.

exception ucxx.exceptions.UCXInvalidAddrError#: Raised when an invalid address is provided.

exception ucxx.exceptions.UCXInvalidParamError#: Raised when an invalid parameter is passed to a UCX function.

exception ucxx.exceptions.UCXLastEndpointFailureError#: Raised on the last endpoint failure in a connection.

exception ucxx.exceptions.UCXLastLinkFailureError#: Raised on the last link failure in a connection.

exception ucxx.exceptions.UCXMessageTruncatedError#: Raised when a received message is truncated.

exception ucxx.exceptions.UCXMsgTruncated#: Raised when a received message is truncated (legacy alias for UCXMessageTruncatedError).

exception ucxx.exceptions.UCXNoDeviceError#: Raised when no suitable device is available.

exception ucxx.exceptions.UCXNoElemError#: Raised when the requested element is not found.

exception ucxx.exceptions.UCXNoMemoryError#: Raised when memory allocation fails.

exception ucxx.exceptions.UCXNoMessageError#: Raised when no message is available.

exception ucxx.exceptions.UCXNoProgressError#: Raised when no progress can be made on the operation.

exception ucxx.exceptions.UCXNoResourceError#: Raised when a required resource is unavailable.

exception ucxx.exceptions.UCXNotConnectedError#: Raised when an operation requires a connection that does not exist.

exception ucxx.exceptions.UCXNotImplementedError#: Raised when a requested feature is not implemented.

exception ucxx.exceptions.UCXOutOfRangeError#: Raised when a value is out of the valid range.

exception ucxx.exceptions.UCXRejectedError#: Raised when a connection or operation is rejected.

exception ucxx.exceptions.UCXShmemSegmentError#: Raised when a shared memory segment operation fails.

exception ucxx.exceptions.UCXSomeConnectsFailedError#: Raised when some connection attempts in a group fail.

exception ucxx.exceptions.UCXTimedOutError#: Raised when an operation times out.

exception ucxx.exceptions.UCXUnreachableError#: Raised when the remote destination is unreachable.

exception ucxx.exceptions.UCXUnsupportedError#: Raised when the requested operation is not supported.

Utilities#

ucxx.utils.get_address(ifname=None, use_ipv6=False)#

Get the address associated with a network interface.

Parameters:

ifname (str) – The network interface name to find the address for. If None, it uses the value of environment variable UCXPY_IFNAME and if UCXPY_IFNAME is not set it defaults to “ib0” An OSError is raised for invalid interfaces.
use_ipv6 (bool) – Whether to get IPv6 addresses instead of the IPv4 default. NOTE: Requires the psutil package.

Raises:

OSError – If no device was found with the specified ifname, or no suitable devices were found when ifname=None.

Returns:

address – The inet addr associated with an interface.

Return type:

Examples

>>> get_address()
'10.33.225.160'

>>> get_address(ifname='lo')
'127.0.0.1'

>>> get_address(ifname='lo', use_ipv6=True)
'::1'

ucxx.utils.get_ucxpy_logger()#

Get UCX-Py logger with custom formatting

Returns:: logger – Logger object
Return type:: logging.Logger

Examples

>>> logger = get_ucxpy_logger()
>>> logger.warning("Test")
[1585175070.2911468] [dgx12:1054] UCXPY  WARNING Test