exceptions

AccessDeniedError()

Authenticated, but not allowed: not an admin, no access to the filespace.

Deliberately not an OSError. When the denied call names a path, the SDK raises FsPermissionError instead.

AuthenticationError()

The token is invalid, expired or revoked. Get a new token.

Deliberately not an OSError, so file-system tools never read it as "the path is missing".

ClientClosedError()

The Client is closed: a call on it after close(), or a call that needs it on an object obtained through it (its class says which); also a call on a closed fsspec LucidLinkFileSystem. Create a new one.

Also a ValueError.

ClientError()

A Client lifecycle or state problem: it could not start or stop, or a call is not valid in its current state (e.g. logging in again with a different token), or a hub reply asked the native client to terminate, or the process was forked while a client ran in its parent. A call on a closed client raises the subclass ClientClosedError.

ConnectError(*args: Any, name: str | None = None, **details: Any)

A Connect data-store operation failed, also when another client holds the data-store lock (retry) or the filespace has the maximum number of data stores.

DataStoreCredentialsError()

The external store rejected the data store's credentials (HTTP 401 / 403 on link, read or rekey). Rekey the data store with working credentials.

Deliberately not an OSError, like AuthenticationError.

DataStoreExistsError()

A data store with this name already exists.

DataStoreInUseError()

The data store still has linked files (remove()). Unlink them first.

DataStoreNotFoundError()

No data store with this name. Also a KeyError (so a Mapping of data stores can raise it from __getitem__); str() is the plain message, without KeyError's quotes.

ExternalObjectNotFoundError()

The external store has no such object (HTTP 404). Errno EIO: never a FileNotFoundError, because the filespace path itself exists.

ExternalStoreError(*args: Any, key: str | None = None, **details: Any)

The external store behind a Connect file failed (an S3 bucket, an HTTP server). Also an FsError (OSError, EIO): filename is the file's path in the filespace.

ExternalStoreUnavailableError()

The external store is unreachable, throttles (HTTP 429) or failed (5xx). Retry later. Also a ConnectionError.

FilespaceAlreadyLinkedError()

The filespace is already linked, with a cache size other than the one asked for (see Workspace.link_filespace()), or the runtime reports it as linked although the SDK is not tracking it. Unlink it first.

FilespaceError(*args: Any, filespace_id: str | None = None)

A Filespace lifecycle or state problem, also when LucidLink services have no endpoint for the filespace yet (e.g. it is still being created) or the filespace cancelled the operation (e.g. while it was being unlinked).

FilespaceInternalError()

The filespace hit an internal error and the SDK unlinked it without a final sync; everything else keeps working. Link it again to recover.

FilespaceNotFoundError()

No filespace with this id: link_filespace() with an unknown id.

Also a KeyError; str() is the plain message, without KeyError's quotes.

FilespaceNotLinkedError()

The Filespace is no longer linked: it was unlinked, or the SDK unlinked it after an internal error. Link it again.

FilespaceSyncError()

The final sync on unlink() or with exit failed, or the SDK unlinked the filespace after an internal error before the final sync: pending changes may not have reached LucidLink services. They stay in the local cache only, and with ephemeral storage are lost when the client is closed. The filespace is unlinked anyway, unless unlinking failed as well: then both errors arrive together in a LucidLinkErrorGroup. A note names the underlying failure: the failed sync, or the FilespaceInternalError that made the SDK unlink the filespace.

FsDirectoryNotEmptyError()

The directory is not empty (ENOTEMPTY, as os.rmdir). No builtin subclass exists.

FsError()

A path-level file-system operation failed.

Also an OSError: errno, strerror, filename (also readable as path) and filename2 (for two-path calls such as move) are set, and str() has the stdlib shape [Errno <n>] <message>: '<path>'. Raised directly, with errno EIO, for failures with no more specific class, and with errno EBUSY (another client holds a lock on the path), ELOOP (a symbolic link), EFBIG (the maximum file size is reached), EINVAL (e.g. a directory moved into itself) or ENOSYS (hard links not supported) for those conditions. A failing external store behind a Connect file is an ExternalStoreError, which is also an FsError.

Like OSError(errno, ...), FsError(errno, strerror[, filename, ...]) called on FsError itself returns the subclass of that errno (FsError(errno.ENOENT, ...) is an FsNotFoundError); its subclasses are never redirected.

FsExistsError()

The path already exists. Also a FileExistsError (EEXIST).

FsIsADirectoryError()

A file was expected but the path is a directory. Also an IsADirectoryError (EISDIR).

FsNoSpaceError()

No space (ENOSPC): a filespace limit was reached (entries, storage, data, or external-file size or count; raise the limit), or the local disk is full. The message says which.

FsNotADirectoryError()

A directory was expected. Also a NotADirectoryError (ENOTDIR).

FsNotFoundError()

The path does not exist. Also a FileNotFoundError (ENOENT).

FsPermissionError()

The operation on this path is not permitted. Also a PermissionError.

errno is EACCES (no access to the path) or EPERM (e.g. a hard link to a directory); or EROFS when the file or the filespace is read-only (code that checks errno == EACCES does not see that case).

IncompatibleVersionError()

This client is too old, or the filespace or KeyStack version is not supported. Upgrade.

InternalError()

A bug, a failed assertion, corrupted data or a broken native contract. Report it. A failure this SDK version cannot classify is a plain LucidLinkError instead.

InvalidArgumentError()

A bad argument value (native InvalidArgument, or Python-side validation).

Also a ValueError. Wrong argument types raise the builtin TypeError instead. Also raised for invalid storage settings (StorageConfig, storage mode), fsspec options, or a configuration the native runtime rejects (including an unreachable cache location).

LucidLinkDeprecationWarning()

A deprecated SDK feature was used. Emitted with stacklevel=2 so the warning points at the caller.

LucidLinkError()

Root of every error the SDK raises on purpose.

Catch it to handle "anything the SDK raised". Most subclasses also inherit a builtin (FileNotFoundError, ConnectionError, ValueError, …), so existing code that catches builtins keeps working.

Raised as itself for a failure this SDK version cannot classify: an HTTP status with no class, or an unknown native error, which the SDK also logs as a warning on the lucidlink logger.

LucidLinkErrorGroup(message: str, exceptions: Iterable[BaseException])

Several failures from one call that works on several filespaces (Workspace.stop, Client.close, the fsspec close / sync_all), or from Filespace.unlink() / with exit when both the final sync (or closing the files still open) and unlinking fail: then the members are a FilespaceSyncError or a FilespaceError (a note names the sync or close failure) and the error from unlinking.

Also an ExceptionGroup. Every member is a LucidLinkError (a member of another type is wrapped in InternalError whose message is the original's type and text); a BaseException such as KeyboardInterrupt is never collected but escapes at once; a member that is not an exception instance raises InternalError. Handle with except*, or iterate group.exceptions.

LucidLinkWarning()

Base class of the SDK's own warnings. A warning that Python's own file objects also give keeps its builtin class: ResourceWarning for a file not closed, and RuntimeWarning for line buffering in binary mode.

NotLoggedInError()

The Client is not logged in. Call login() first.

OperationTimeoutError()

The operation timed out, or a service answered 408. For a mutating call the outcome is unknown.

Also a TimeoutError (ETIMEDOUT).

RateLimitedError()

LucidLink services answered 429. Back off, then retry.

A sibling of ServiceUnavailableError, deliberately not a ConnectionError: the service is reachable and asked the caller to slow down.

ServiceUnavailableError()

LucidLink services, the hub or a store are unreachable or answered 5xx. Retry later.

Also a ConnectionError. errno is None (an ECONNREFUSED would wrongly claim a ConnectionRefusedError); filename is set when the failed call named a path.

UnsupportedOperationError()

The operation is not available here: Connect on a filespace without it, a data-store kind the filespace version does not support, an unsupported native operation.

Deliberately not a NotImplementedError (that is a RuntimeError).