Skip to main content

Exceptions

Exception Hierarchy​

DqliteError (base)
├── NodeError
│   ├── NodeStartError
│   ├── NodeStopError
│   ├── NodeAlreadyRunningError
│   └── NodeNotRunningError
├── ClientError
│   ├── NoLeaderError
│   ├── ClientConnectionError
│   └── ClientClosedError
├── ClusterError
│   ├── ClusterJoinError
│   └── ClusterQuorumLostError
├── ResourceError
│   └── MemoryError
└── SegmentationFault

DqliteError​

Base exception for all dqlite errors.

This is the base class for all dqlite-related exceptions. It provides context about the operation that failed and supports error recovery.

NodeError​

Base exception for node-related errors.

Raised when operations on a dqlite Node fail, such as starting, stopping, or communicating with the node.

Attributes: node_id: Unique identifier of the node (if known). node_address: Network address of the node (if known).

Example:

>>> try:
...     node.start()
... except NodeError as e:
...     print(f"Node {e.node_id} failed: {e}")

NodeStartError​

Raised when a node fails to start.

This can occur due to:

  • Port already in use
  • Invalid data directory
  • Corrupted database files
  • Permission issues

Example:

>>> try:
...     node = Node("127.0.0.1:9001", "/data")
...     node.start()
... except NodeStartError as e:
...     print(f"Failed to start node: {e}")
...     # Check port availability, permissions, etc.

NodeStopError​

Raised when a node fails to stop cleanly.

This exception is marked as WARNING severity because stop failures are often not critical - the process may be exiting anyway.

ClientError​

Base exception for client-related errors.

Raised when Client operations fail, such as connecting to the cluster, adding nodes, or querying cluster state.

Example:

>>> try:
...     client = Client(["127.0.0.1:9001", "127.0.0.1:9002"])
...     leader = client.leader()
... except ClientError as e:
...     print(f"Client operation failed: {e}")

NoLeaderError​

Raised when the cluster has no elected leader.

This can happen temporarily during:

  • Leader election after a node failure
  • Network partitions
  • Cluster startup before quorum is achieved

Operations should be retried after a brief delay (typically 1-5 seconds).

Example:

>>> import time
>>> from dqlitepy.exceptions import NoLeaderError
>>>
>>> max_retries = 5
>>> for attempt in range(max_retries):
...     try:
...         leader = client.leader()
...         break
...     except NoLeaderError:
...         if attempt < max_retries - 1:
...             time.sleep(1)
...         else:
...             raise

ClusterError​

Base exception for cluster management errors.

ClusterJoinError​

Raised when a node fails to join the cluster.

ResourceError​

Base exception for resource management errors.

MemoryError​

Raised when memory allocation fails.

SegmentationFault​

Raised when a segmentation fault is detected.

This is a fatal error that indicates memory corruption or undefined behavior in the C library.