maestral.errors

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.

exception maestral.errors.MaestralApiError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=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 (Optional[str]) – Dropbox path of the file that caused the error.

  • dbx_path_dst (Optional[str]) – Dropbox destination path of the file that caused the error. This should be set for instance when error occurs when moving an item.

  • local_path (Optional[str]) – Local path of the file that caused the error.

  • local_path_dst (Optional[str]) – Local destination path of the file that caused the error. This should be set for instance when error occurs when moving an item.

Return type

None

exception maestral.errors.SyncError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Base class for recoverable sync issues.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.InsufficientPermissionsError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.InsufficientSpaceError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.PathError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.NotFoundError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.ConflictError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.FileConflictError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.ConflictError

Raised when trying to create a file which already exists.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.FolderConflictError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

Raised when trying to create or folder which already exists.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.IsAFolderError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.NotAFolderError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.DropboxServerError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

Raised in case of internal Dropbox errors.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.RestrictedContentError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.UnsupportedFileError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.FileSizeError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.FileReadError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.SyncError

Raised when reading a local file failed.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.DropboxConnectionError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when the connection to Dropbox fails

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.CancelledError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when syncing is cancelled by the user.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.NotLinkedError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when no Dropbox account is linked.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.InvalidDbidError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.KeyringAccessError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.NoDropboxDirError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when the local Dropbox folder cannot be found.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.CacheDirError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when creating the cache directory fails.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.InotifyError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.OutOfMemoryError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when there is insufficient memory to complete an operation.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.DatabaseError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when reading or writing to the database fails.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.DropboxAuthError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when authentication fails.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.TokenExpiredError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.DropboxAuthError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.TokenRevokedError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.DropboxAuthError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.CursorResetError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.BadInputError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.BusyError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.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 (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.UnsupportedFileTypeForDiff(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

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

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None

exception maestral.errors.SharedLinkError(title, message='', dbx_path=None, dbx_path_dst=None, local_path=None, local_path_dst=None)[source]

Bases: maestral.errors.MaestralApiError

Raised when creating a shared link fails.

Parameters
  • title (str) –

  • message (str) –

  • dbx_path (Optional[str]) –

  • dbx_path_dst (Optional[str]) –

  • local_path (Optional[str]) –

  • local_path_dst (Optional[str]) –

Return type

None