maestral.exceptions

This module defines Maestral’s error classes. It should be kept free of memory heavy imports.

All errors inherit from MaestralApiError which has title and message attributes to display the error to the user. Errors which are related to syncing a specific file or folder inherit from SyncError, a subclass of MaestralApiError.

Module Contents

exception maestral.exceptions.MaestralApiError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: Exception

Base class for Maestral errors

MaestralApiError provides attributes that can be used to generate human-readable error messages and metadata regarding affected file paths (if any).

Errors originating from the Dropbox API or the ‘local API’ both inherit from MaestralApiError.

Parameters:

  • title (str) – A short description of the error type. This can be used in a CLI or GUI to give a short error summary.

  • message (str) – A more verbose description which can include instructions on how to proceed to fix the error.

  • dbx_path (str | None) – Dropbox path of the item that caused the error.

  • dbx_path_from (str | None) – Dropbox origin path of the item that caused the error. This should be set for instance when error occurs when moving an item.

  • local_path (str | None) – Local path of the item that caused the error.

  • local_path_from (str | None) – Local origin path of the item that caused the error. This should be set for instance when error occurs when moving an item.

exception maestral.exceptions.SyncError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Base class for recoverable sync issues.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DataCorruptionError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when data is corrupted in transit during upload or download.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DataChangedError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when file changes during upload.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.InsufficientPermissionsError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when accessing a file or folder fails due to insufficient permissions, both locally and on Dropbox servers.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.InsufficientSpaceError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when the Dropbox account or local drive has insufficient storage space.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.PathError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when there is an issue with the provided file or folder path such as invalid characters or a too long file name.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.NotFoundError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when a file or folder is requested but does not exist.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.ConflictError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when trying to create a file or folder which already exists.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.FileConflictError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: ConflictError

Raised when trying to create a file which already exists.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.FolderConflictError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when trying to create or folder which already exists.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.IsAFolderError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when a file is required but a folder is provided.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.NotAFolderError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when a folder is required but a file is provided.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DropboxServerError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised in case of internal Dropbox errors.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.RestrictedContentError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when trying to sync restricted content, for instance when adding a file with a DMCA takedown notice to a public folder.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.UnsupportedFileError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when this file type cannot be downloaded but only exported. This is the case for G-suite files.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.FileSizeError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when attempting to upload a file larger than 350 GB in an upload session or larger than 150 MB in a single upload. Also raised when attempting to download a file with a size that exceeds file system’s limit.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.FileReadError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when reading a local file failed.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.SymlinkError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: SyncError

Raised when we cannot sync a symlink.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DropboxConnectionError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when the connection to Dropbox fails

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.CancelledError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when syncing is cancelled by the user.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.NotLinkedError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when no Dropbox account is linked.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.InvalidDbidError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when the given Dropbox ID does not correspond to an existing account.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.KeyringAccessError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when retrieving a saved auth token from the user keyring fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.NoDropboxDirError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when the local Dropbox folder cannot be found.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.CacheDirError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when creating the cache directory fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.InotifyError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when the local Dropbox folder is too large to monitor with inotify.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.OutOfMemoryError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when there is insufficient memory to complete an operation.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DatabaseError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when reading or writing to the database fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.DropboxAuthError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when authentication fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.TokenExpiredError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: DropboxAuthError

Raised when authentication fails because the user’s token has expired.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.TokenRevokedError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: DropboxAuthError

Raised when authentication fails because the user’s token has been revoked.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.CursorResetError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when the cursor used for a longpoll or list-folder request has been invalidated. Dropbox will very rarely invalidate a cursor. If this happens, a new cursor for the respective folder has to be obtained through files_list_folder. This may require re-syncing the entire Dropbox.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.BadInputError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when an API request is made with bad input. This should not happen during syncing but only in case of manual API calls.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.BusyError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when trying to perform an action which is only possible in the idle state and we cannot block or queue the job.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.UnsupportedFileTypeForDiff(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when a diff for an unsupported file type was issued.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.SharedLinkError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when creating a shared link fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.PathRootError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when making an API call with an invalid path root header.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)

exception maestral.exceptions.UpdateCheckError(title, message='', dbx_path=None, dbx_path_from=None, local_path=None, local_path_from=None)[source]

Bases: MaestralApiError

Raised when checking for updates fails.

Parameters:

  • title (str)

  • message (str)

  • dbx_path (str | None)

  • dbx_path_from (str | None)

  • local_path (str | None)

  • local_path_from (str | None)