Module Neodriver_core.Errors

Error taxonomy (server and driver errors).

Error taxonomy for the Neo4j driver.

See errors.ml for the implementation.

type classification =
  1. | Client
  2. | Database
  3. | Transient
  4. | Unknown
    (*

    Classification of a server-reported error, derived from its code.

    *)
type server_error = {
  1. code : string;
  2. message : string;
  3. classification : classification;
  4. retryable : bool;
  5. gql_status : string option;
  6. status_description : string option;
  7. diagnostic_record : (string * Values.t) list option;
  8. gql_classification : string option;
  9. raw_classification : string option;
  10. cause : server_error option;
  11. idempotent : bool;
}

A server (Neo4j) error as reported over the wire. gql_status is the GQL status code from the FAILURE metadata (Bolt >= 5.2 / 5.7), when the server provides one; with a Bolt 5.7 server it comes with a status_description, the diagnostic_record (its default entries filled in), the parsed gql_classification and raw_classification and an optional nested cause error. idempotent is the Bolt >= 6.0 diagnostic_record._idempotent flag: the server guarantees the failed request did not alter any database state, so an auto-commit RUN failing with such an error may be retried safely.

type specific =
  1. | Constraint
  2. | Cypher_syntax
  3. | Cypher_type
  4. | Forbidden
  5. | Forbidden_on_read_only_database
  6. | Auth
  7. | Token_expired
  8. | Not_a_leader
  9. | Database_unavailable
  10. | Other
    (*

    Well-known server errors, recognised by their neo4j code.

    *)
type t =
  1. | Neo4j of server_error
  2. | Session_expired of string
  3. | Service_unavailable of string
  4. | Routing_service_unavailable of string
  5. | Write_service_unavailable of string
  6. | Read_service_unavailable of string
  7. | Incomplete_commit of string
  8. | Session_error of string
  9. | Transaction_error of string
  10. | Transaction_nesting_error of string
  11. | Result_failed_error of string
  12. | Result_consumed_error of string
  13. | Result_not_single_error of string
  14. | Broken_record_error of string
  15. | Configuration_error of string
  16. | Auth_configuration_error of string
  17. | Certificate_configuration_error of string
  18. | Unsupported_server_product of string
  19. | Connection_pool_error of string
  20. | Connection_acquisition_timeout of string
    (*

    Driver and server errors.

    *)
type failures = {
  1. last : t;
  2. all : t list;
}

All errors from a failed multi-address connection attempt: last is the most recent failure and all lists every failure in order of occurrence. The OCaml analogue of the Python driver's exception aggregation when no resolved address can be connected.

val is_retryable : t -> bool

Whether an error is safe to retry a transaction after.

val make_retryable : t -> t

make_retryable error returns error with its retryability forced to true (the OCaml analogue of the Python driver marking a Neo4j error retryable once an auth manager handled it); driver errors are returned unchanged.

val of_neo4j_code : code:string -> message:string -> t

Build a server error from a neo4j code and message, applying the classification and legacy re-write maps.

val of_neo4j_code_with_gql_status : gql_status:string option -> code:string -> message:string -> t

Like of_neo4j_code, but also records the gql_status from the Bolt >= 5.2 FAILURE metadata.

val server_error_of_neo4j_gql : code:string -> message:string -> gql_status:string -> status_description:string -> diagnostic_record:(string * Values.t) list option -> gql_classification:string -> raw_classification:string option -> cause:server_error option -> server_error

Build a Bolt 5.7 style server error with its GQL status fields, diagnostic record and nested cause.

val idempotent : t -> bool

Whether the server marked the failure idempotent (an auto-commit RUN failing with it may be retried); false for driver errors and unmarked server errors.

val status_description : t -> string option

The GQL status description of a server error, if any.

val diagnostic_record : t -> (string * Values.t) list option

The diagnostic record of a server error (with its default entries filled in), if any.

val gql_classification : t -> string option

The parsed GQL classification of a server error ("UNKNOWN" when the server did not provide a known one), if any.

val raw_classification : t -> string option

The raw _classification string of a server error's diagnostic record, when it is a string.

val cause : t -> server_error option

The nested server error a failure reported as its cause, if any.

val mark_idempotent : t -> t

mark_idempotent error returns error with its idempotent marker set (used when the Bolt >= 6 diagnostic_record._idempotent flag is present); driver errors are returned unchanged.

val clear_idempotent : t -> t

clear_idempotent error returns error without its idempotent marker (used for a failure that answered a TELEMETRY rather than the RUN itself); driver errors are returned unchanged.

val code : t -> string option

The neo4j code of a server error, or None for driver errors.

val message : t -> string

The message of an error.

val classification : t -> classification option

The classification of a server error, or None for driver errors.

val specific : t -> specific

The well-known specific error kind, if any.

val unauthenticates_all_connections : t -> bool

Whether the error invalidates the authentication of all connections (AuthorizationExpired).

val has_security_code : t -> bool

Whether the error carries a Neo.ClientError.Security.* code.

val is_fatal_during_discovery : t -> bool

Whether the error should fail fast during routing discovery.

val to_string : t -> string

Render an error as a human-readable string.

val classification_to_string : classification -> string

Render a classification as its neo4j string ("ClientError", ...).

val specific_to_string : specific -> string

Render a specific error kind as a string.