exceptions

LucidLink Python Library - Exception Classes

This module defines custom exception classes for LucidLink-specific errors (client lifecycle, filespace operations, authentication, configuration).

Filesystem operations raise standard Python exceptions for seamless interoperability with existing Python code:

FileNotFoundError -- file or directory does not exist
FileExistsError -- file or directory already exists
NotADirectoryError -- expected a directory
IsADirectoryError -- expected a file, got a directory
PermissionError -- insufficient permissions or wrong credentials
ValueError -- invalid path or argument
TimeoutError -- operation timed out
ConnectionError -- network/transport failure
OSError -- general system-level error

This means standard try/except patterns work as expected

try:    data = filespace.fs.read_file("/missing.txt")except FileNotFoundError:    print("File does not exist")except PermissionError:    print("No read access")

exception

lucidlink.exceptions.AuthenticationError

AuthenticationError()

Raised when authentication fails.

Note: Most authentication errors are mapped to Python's PermissionError. This is for authentication-specific context where needed.

exception

lucidlink.exceptions.ClientError

ClientError()

Raised when Client lifecycle operations fail.

Examples: client initialization failed, runtime startup failed, teardown error. Authentication failures use AuthenticationError instead.

exception

lucidlink.exceptions.ConfigurationError

ConfigurationError()

Raised when configuration is invalid.

Inherits from both LucidLinkError and ValueError for compatibility.

deprecatedexception

lucidlink.exceptions.DaemonError

This API is deprecated.

DaemonError()

Raised when daemon operations fail.

Examples: daemon already running, daemon not started, daemon initialization failed

Deprecated. Used by the deprecated Daemon class. New code should use Client and catch ClientError.

exception

lucidlink.exceptions.FilespaceAlreadyLinkedError

FilespaceAlreadyLinkedError(*args, filespace_id: str = '')

Raised when linking a filespace that is already linked under a different identifier (e.g. linked by id earlier, now requested by name).

link_filespace() catches this internally to return the existing live Filespace — its idempotency contract — so callers rarely see it. It surfaces only if the existing link can no longer be resolved.

The runtime classifies this case by exception type (the AlreadyLinkedException FFI category) and carries the canonical id as a structured field, surfaced here as the filespace_id attribute — it is never parsed out of the human message. A reworded message therefore changes nothing, and the error can never be mistaken for an unrelated failure such as a network drop.

exception

lucidlink.exceptions.FilespaceError

FilespaceError()

Raised when filespace operations fail.

Examples: filespace not linked, filespace connection failed, invalid filespace ID

exception

lucidlink.exceptions.FilespaceInternalError

FilespaceInternalError(*args, filespace_id: str = '')

Raised when a filespace hits an internal error. The SDK unlinks the affected filespace itself (unsynchronized writes are lost); everything else keeps working. To recover, link the filespace again.

The filespace_id attribute identifies the affected filespace; it may be empty on errors raised directly from a native call.

exception

lucidlink.exceptions.LucidLinkError

LucidLinkError()

Base class for all LucidLink-specific exceptions.

This is a base exception that can be caught to handle any LucidLink error. Most specific errors inherit from Python builtins for better compatibility.