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[source]

Bases: LucidLinkError

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[source]

Bases: LucidLinkError

Raised when Client lifecycle operations fail.

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

exception lucidlink.exceptions.ConfigurationError[source]

Bases: LucidLinkError, ValueError

Raised when configuration is invalid.

Inherits from both LucidLinkError and ValueError for compatibility.

exception lucidlink.exceptions.DaemonError[source]

Bases: LucidLinkError

Raised when daemon operations fail.

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

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

exception lucidlink.exceptions.FilespaceAlreadyLinkedError(*args, filespace_id: str = '')[source]

Bases: FilespaceError

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[source]

Bases: LucidLinkError

Raised when filespace operations fail.

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

exception lucidlink.exceptions.LucidLinkError[source]

Bases: Exception

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.