Error Handling

All python-arango exceptions inherit arango.exceptions.ArangoError, which splits into subclasses arango.exceptions.ArangoServerError and arango.exceptions.ArangoClientError.

Server Errors

arango.exceptions.ArangoServerError exceptions lightly wrap non-2xx HTTP responses coming from ArangoDB. Each exception object contains the error message, error code and HTTP request response details.

Example:

from arango import ArangoClient, ArangoServerError, DocumentInsertError

# Initialize the ArangoDB client.
client = ArangoClient()

# Connect to "test" database as root user.
db = client.db('test', username='root', password='passwd')

# Get the API wrapper for "students" collection.
students = db.collection('students')

try:
    students.insert({'_key': 'John'})
    students.insert({'_key': 'John'})  # duplicate key error

except DocumentInsertError as exc:

    assert isinstance(exc, ArangoServerError)
    assert exc.source == 'server'

    exc.message           # Exception message usually from ArangoDB
    exc.error_message     # Raw error message from ArangoDB
    exc.error_code        # Error code from ArangoDB
    exc.url               # URL (API endpoint)
    exc.http_method       # HTTP method (e.g. "POST")
    exc.http_headers      # Response headers
    exc.http_code         # Status code (e.g. 200)

    # You can inspect the ArangoDB response directly.
    response = exc.response
    response.method       # HTTP method (e.g. "POST")
    response.headers      # Response headers
    response.url          # Full request URL
    response.is_success   # Set to True if HTTP code is 2XX
    response.body         # JSON-deserialized response body
    response.raw_body     # Raw string response body
    response.status_text  # Status text (e.g "OK")
    response.status_code  # Status code (e.g. 200)
    response.error_code   # Error code from ArangoDB

    # You can also inspect the request sent to ArangoDB.
    request = exc.request
    request.method        # HTTP method (e.g. "post")
    request.endpoint      # API endpoint starting with "/_api"
    request.headers       # Request headers
    request.params        # URL parameters
    request.data          # Request payload
    request.read          # Read collections (used for transactions only)
    request.write         # Write collections (used for transactions only)
    request.command       # ArangoSh command (used for transactions only)

See Response and Request for reference.

Client Errors

arango.exceptions.ArangoClientError exceptions originate from python-arango client itself. They do not contain error codes nor HTTP request response details.

Example:

from arango import ArangoClient, ArangoClientError, DocumentParseError

# Initialize the ArangoDB client.
client = ArangoClient()

# Connect to "test" database as root user.
db = client.db('test', username='root', password='passwd')

# Get the API wrapper for "students" collection.
students = db.collection('students')

try:
    students.get({'_id': 'invalid_id'})  # malformed document

except DocumentParseError as exc:

    assert isinstance(exc, ArangoClientError)
    assert exc.source == 'client'

    # Only the error message is set.
    error_message = exc.message
    assert exc.error_code is None
    assert exc.error_message is None
    assert exc.url is None
    assert exc.http_method is None
    assert exc.http_code is None
    assert exc.http_headers is None
    assert exc.response is None
    assert exc.request is None

Exceptions

Below are all exceptions from python-arango.

exception arango.exceptions.AQLCacheClearError(resp, request, msg=None)

Failed to clear the query cache.

exception arango.exceptions.AQLCacheConfigureError(resp, request, msg=None)

Failed to configure query cache properties.

exception arango.exceptions.AQLCacheEntriesError(resp, request, msg=None)

Failed to retrieve AQL cache entries.

exception arango.exceptions.AQLCachePropertiesError(resp, request, msg=None)

Failed to retrieve query cache properties.

exception arango.exceptions.AQLFunctionCreateError(resp, request, msg=None)

Failed to create AQL user function.

exception arango.exceptions.AQLFunctionDeleteError(resp, request, msg=None)

Failed to delete AQL user function.

exception arango.exceptions.AQLFunctionListError(resp, request, msg=None)

Failed to retrieve AQL user functions.

exception arango.exceptions.AQLQueryClearError(resp, request, msg=None)

Failed to clear slow AQL queries.

exception arango.exceptions.AQLQueryExecuteError(resp, request, msg=None)

Failed to execute query.

exception arango.exceptions.AQLQueryExplainError(resp, request, msg=None)

Failed to parse and explain query.

exception arango.exceptions.AQLQueryKillError(resp, request, msg=None)

Failed to kill the query.

exception arango.exceptions.AQLQueryListError(resp, request, msg=None)

Failed to retrieve running AQL queries.

exception arango.exceptions.AQLQueryTrackingGetError(resp, request, msg=None)

Failed to retrieve AQL tracking properties.

exception arango.exceptions.AQLQueryTrackingSetError(resp, request, msg=None)

Failed to configure AQL tracking properties.

exception arango.exceptions.AQLQueryValidateError(resp, request, msg=None)

Failed to parse and validate query.

exception arango.exceptions.ArangoClientError(msg)

Base class for errors originating from python-arango client.

Parameters:

msg (str | unicode) – Error message.

Variables:
  • source (str | unicode) – Source of the error (always set to “client”).
  • message (str | unicode) – Error message.
exception arango.exceptions.ArangoError

Base class for all exceptions in python-arango.

exception arango.exceptions.ArangoServerError(resp, request, msg=None)

Base class for errors originating from ArangoDB server.

Parameters:
Variables:
  • source (str | unicode) – Source of the error (always set to “server”).
  • message (str | unicode) – Exception message.
  • url (str | unicode) – API URL.
  • response (arango.response.Response) – HTTP response object.
  • request (arango.request.Request) – HTTP request object.
  • http_method (str | unicode) – HTTP method in lowercase (e.g. “post”).
  • http_code (int) – HTTP status code.
  • http_headers (requests.structures.CaseInsensitiveDict | dict) – Response headers.
  • error_code (int) – Error code from ArangoDB server.
  • error_message (str | unicode) – Raw error message from ArangoDB server.
exception arango.exceptions.AsyncExecuteError(resp, request, msg=None)

Failed to execute async API request.

exception arango.exceptions.AsyncJobCancelError(resp, request, msg=None)

Failed to cancel async job.

exception arango.exceptions.AsyncJobClearError(resp, request, msg=None)

Failed to clear async job results.

exception arango.exceptions.AsyncJobListError(resp, request, msg=None)

Failed to retrieve async jobs.

exception arango.exceptions.AsyncJobResultError(resp, request, msg=None)

Failed to retrieve async job result.

exception arango.exceptions.AsyncJobStatusError(resp, request, msg=None)

Failed to retrieve async job status.

exception arango.exceptions.BatchExecuteError(resp, request, msg=None)

Failed to execute batch API request.

exception arango.exceptions.BatchJobResultError(msg)

Failed to retrieve batch job result.

exception arango.exceptions.BatchStateError(msg)

The batch object was in a bad state.

exception arango.exceptions.CollectionChecksumError(resp, request, msg=None)

Failed to retrieve collection checksum.

exception arango.exceptions.CollectionConfigureError(resp, request, msg=None)

Failed to configure collection properties.

exception arango.exceptions.CollectionCreateError(resp, request, msg=None)

Failed to create collection.

exception arango.exceptions.CollectionDeleteError(resp, request, msg=None)

Failed to delete collection.

exception arango.exceptions.CollectionListError(resp, request, msg=None)

Failed to retrieve collections.

exception arango.exceptions.CollectionLoadError(resp, request, msg=None)

Failed to load collection.

exception arango.exceptions.CollectionPropertiesError(resp, request, msg=None)

Failed to retrieve collection properties.

exception arango.exceptions.CollectionRenameError(resp, request, msg=None)

Failed to rename collection.

exception arango.exceptions.CollectionRevisionError(resp, request, msg=None)

Failed to retrieve collection revision.

exception arango.exceptions.CollectionRotateJournalError(resp, request, msg=None)

Failed to rotate collection journal.

exception arango.exceptions.CollectionStatisticsError(resp, request, msg=None)

Failed to retrieve collection statistics.

exception arango.exceptions.CollectionTruncateError(resp, request, msg=None)

Failed to truncate collection.

exception arango.exceptions.CollectionUnloadError(resp, request, msg=None)

Failed to unload collection.

exception arango.exceptions.CursorCloseError(resp, request, msg=None)

Failed to delete the cursor result from server.

exception arango.exceptions.CursorEmptyError(msg)

The current batch in cursor was empty.

exception arango.exceptions.CursorNextError(resp, request, msg=None)

Failed to retrieve the next result batch from server.

exception arango.exceptions.CursorStateError(msg)

The cursor object was in a bad state.

exception arango.exceptions.DatabaseCreateError(resp, request, msg=None)

Failed to create database.

exception arango.exceptions.DatabaseDeleteError(resp, request, msg=None)

Failed to delete database.

exception arango.exceptions.DatabaseListError(resp, request, msg=None)

Failed to retrieve databases.

exception arango.exceptions.DatabasePropertiesError(resp, request, msg=None)

Failed to retrieve database properties.

exception arango.exceptions.DocumentCountError(resp, request, msg=None)

Failed to retrieve document count.

exception arango.exceptions.DocumentDeleteError(resp, request, msg=None)

Failed to delete document.

exception arango.exceptions.DocumentGetError(resp, request, msg=None)

Failed to retrieve document.

exception arango.exceptions.DocumentIDsError(resp, request, msg=None)

Failed to retrieve document IDs.

exception arango.exceptions.DocumentInError(resp, request, msg=None)

Failed to check whether document exists.

exception arango.exceptions.DocumentInsertError(resp, request, msg=None)

Failed to insert document.

exception arango.exceptions.DocumentKeysError(resp, request, msg=None)

Failed to retrieve document keys.

exception arango.exceptions.DocumentParseError(msg)

Failed to parse document input.

exception arango.exceptions.DocumentReplaceError(resp, request, msg=None)

Failed to replace document.

exception arango.exceptions.DocumentRevisionError(resp, request, msg=None)

The expected and actual document revisions mismatched.

exception arango.exceptions.DocumentUpdateError(resp, request, msg=None)

Failed to update document.

exception arango.exceptions.EdgeDefinitionCreateError(resp, request, msg=None)

Failed to create edge definition.

exception arango.exceptions.EdgeDefinitionDeleteError(resp, request, msg=None)

Failed to delete edge definition.

exception arango.exceptions.EdgeDefinitionListError(resp, request, msg=None)

Failed to retrieve edge definitions.

exception arango.exceptions.EdgeDefinitionReplaceError(resp, request, msg=None)

Failed to replace edge definition.

exception arango.exceptions.EdgeListError(resp, request, msg=None)

Failed to retrieve edges coming in and out of a vertex.

exception arango.exceptions.FoxxCommitError(resp, request, msg=None)

Failed to commit local Foxx service state.

exception arango.exceptions.FoxxConfigGetError(resp, request, msg=None)

Failed to retrieve Foxx service configuration.

exception arango.exceptions.FoxxConfigReplaceError(resp, request, msg=None)

Failed to replace Foxx service configuration.

exception arango.exceptions.FoxxConfigUpdateError(resp, request, msg=None)

Failed to update Foxx service configuration.

exception arango.exceptions.FoxxDependencyGetError(resp, request, msg=None)

Failed to retrieve Foxx service dependencies.

exception arango.exceptions.FoxxDependencyReplaceError(resp, request, msg=None)

Failed to replace Foxx service dependencies.

exception arango.exceptions.FoxxDependencyUpdateError(resp, request, msg=None)

Failed to update Foxx service dependencies.

exception arango.exceptions.FoxxDevModeDisableError(resp, request, msg=None)

Failed to disable development mode for Foxx service.

exception arango.exceptions.FoxxDevModeEnableError(resp, request, msg=None)

Failed to enable development mode for Foxx service.

exception arango.exceptions.FoxxDownloadError(resp, request, msg=None)

Failed to download Foxx service bundle.

exception arango.exceptions.FoxxReadmeGetError(resp, request, msg=None)

Failed to retrieve Foxx service readme.

exception arango.exceptions.FoxxScriptListError(resp, request, msg=None)

Failed to retrieve Foxx service scripts.

exception arango.exceptions.FoxxScriptRunError(resp, request, msg=None)

Failed to run Foxx service script.

exception arango.exceptions.FoxxServiceCreateError(resp, request, msg=None)

Failed to create Foxx service.

exception arango.exceptions.FoxxServiceDeleteError(resp, request, msg=None)

Failed to delete Foxx services.

exception arango.exceptions.FoxxServiceGetError(resp, request, msg=None)

Failed to retrieve Foxx service metadata.

exception arango.exceptions.FoxxServiceListError(resp, request, msg=None)

Failed to retrieve Foxx services.

exception arango.exceptions.FoxxServiceReplaceError(resp, request, msg=None)

Failed to replace Foxx service.

exception arango.exceptions.FoxxServiceUpdateError(resp, request, msg=None)

Failed to update Foxx service.

exception arango.exceptions.FoxxSwaggerGetError(resp, request, msg=None)

Failed to retrieve Foxx service swagger.

exception arango.exceptions.FoxxTestRunError(resp, request, msg=None)

Failed to run Foxx service tests.

exception arango.exceptions.GraphCreateError(resp, request, msg=None)

Failed to create the graph.

exception arango.exceptions.GraphDeleteError(resp, request, msg=None)

Failed to delete the graph.

exception arango.exceptions.GraphListError(resp, request, msg=None)

Failed to retrieve graphs.

exception arango.exceptions.GraphPropertiesError(resp, request, msg=None)

Failed to retrieve graph properties.

exception arango.exceptions.GraphTraverseError(resp, request, msg=None)

Failed to execute graph traversal.

exception arango.exceptions.IndexCreateError(resp, request, msg=None)

Failed to create collection index.

exception arango.exceptions.IndexDeleteError(resp, request, msg=None)

Failed to delete collection index.

exception arango.exceptions.IndexListError(resp, request, msg=None)

Failed to retrieve collection indexes.

exception arango.exceptions.IndexLoadError(resp, request, msg=None)

Failed to load indexes into memory.

exception arango.exceptions.PermissionGetError(resp, request, msg=None)

Failed to retrieve user permission.

exception arango.exceptions.PermissionListError(resp, request, msg=None)

Failed to list user permissions.

exception arango.exceptions.PermissionResetError(resp, request, msg=None)

Failed to reset user permission.

exception arango.exceptions.PermissionUpdateError(resp, request, msg=None)

Failed to update user permission.

exception arango.exceptions.PregelJobCreateError(resp, request, msg=None)

Failed to create Pregel job.

exception arango.exceptions.PregelJobDeleteError(resp, request, msg=None)

Failed to delete Pregel job.

exception arango.exceptions.PregelJobGetError(resp, request, msg=None)

Failed to retrieve Pregel job details.

exception arango.exceptions.ServerConnectionError(msg)

Failed to connect to ArangoDB server.

exception arango.exceptions.ServerDetailsError(resp, request, msg=None)

Failed to retrieve server details.

exception arango.exceptions.ServerEchoError(resp, request, msg=None)

Failed to retrieve details on last request.

exception arango.exceptions.ServerEndpointsError(resp, request, msg=None)

Failed to retrieve server endpoints.

exception arango.exceptions.ServerEngineError(resp, request, msg=None)

Failed to retrieve database engine.

exception arango.exceptions.ServerLogLevelError(resp, request, msg=None)

Failed to retrieve server log levels.

exception arango.exceptions.ServerLogLevelSetError(resp, request, msg=None)

Failed to set server log levels.

exception arango.exceptions.ServerReadLogError(resp, request, msg=None)

Failed to retrieve global log.

exception arango.exceptions.ServerReloadRoutingError(resp, request, msg=None)

Failed to reload routing details.

exception arango.exceptions.ServerRequiredDBVersionError(resp, request, msg=None)

Failed to retrieve server target version.

exception arango.exceptions.ServerRoleError(resp, request, msg=None)

Failed to retrieve server role in a cluster.

exception arango.exceptions.ServerRunTestsError(resp, request, msg=None)

Failed to execute server tests.

exception arango.exceptions.ServerShutdownError(resp, request, msg=None)

Failed to initiate shutdown sequence.

exception arango.exceptions.ServerStatisticsError(resp, request, msg=None)

Failed to retrieve server statistics.

exception arango.exceptions.ServerStatusError(resp, request, msg=None)

Failed to retrieve server status.

exception arango.exceptions.ServerTimeError(resp, request, msg=None)

Failed to retrieve server system time.

exception arango.exceptions.ServerVersionError(resp, request, msg=None)

Failed to retrieve server version.

exception arango.exceptions.TaskCreateError(resp, request, msg=None)

Failed to create server task.

exception arango.exceptions.TaskDeleteError(resp, request, msg=None)

Failed to delete server task.

exception arango.exceptions.TaskGetError(resp, request, msg=None)

Failed to retrieve server task details.

exception arango.exceptions.TaskListError(resp, request, msg=None)

Failed to retrieve server tasks.

exception arango.exceptions.TransactionExecuteError(resp, request, msg=None)

Failed to execute transaction API request

exception arango.exceptions.TransactionJobResultError(msg)

Failed to retrieve transaction job result.

exception arango.exceptions.TransactionStateError(msg)

The transaction object was in bad state.

exception arango.exceptions.UserCreateError(resp, request, msg=None)

Failed to create user.

exception arango.exceptions.UserDeleteError(resp, request, msg=None)

Failed to delete user.

exception arango.exceptions.UserGetError(resp, request, msg=None)

Failed to retrieve user details.

exception arango.exceptions.UserListError(resp, request, msg=None)

Failed to retrieve users.

exception arango.exceptions.UserReplaceError(resp, request, msg=None)

Failed to replace user.

exception arango.exceptions.UserUpdateError(resp, request, msg=None)

Failed to update user.

exception arango.exceptions.VertexCollectionCreateError(resp, request, msg=None)

Failed to create vertex collection.

exception arango.exceptions.VertexCollectionDeleteError(resp, request, msg=None)

Failed to delete vertex collection.

exception arango.exceptions.VertexCollectionListError(resp, request, msg=None)

Failed to retrieve vertex collections.

exception arango.exceptions.ViewCreateError(resp, request, msg=None)

Failed to create view.

exception arango.exceptions.ViewDeleteError(resp, request, msg=None)

Failed to delete view.

exception arango.exceptions.ViewGetError(resp, request, msg=None)

Failed to retrieve view details.

exception arango.exceptions.ViewListError(resp, request, msg=None)

Failed to retrieve views.

exception arango.exceptions.ViewRenameError(resp, request, msg=None)

Failed to rename view.

exception arango.exceptions.ViewReplaceError(resp, request, msg=None)

Failed to replace view.

exception arango.exceptions.ViewUpdateError(resp, request, msg=None)

Failed to update view.

exception arango.exceptions.WALConfigureError(resp, request, msg=None)

Failed to configure WAL properties.

exception arango.exceptions.WALFlushError(resp, request, msg=None)

Failed to flush WAL.

exception arango.exceptions.WALPropertiesError(resp, request, msg=None)

Failed to retrieve WAL properties.

exception arango.exceptions.WALTransactionListError(resp, request, msg=None)

Failed to retrieve running WAL transactions.