FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Error handling

This page describes how Fauna communicates errors to client applications, and how you can access details from Fauna errors.

Each Fauna driver attempts to feel "native" in each host language, while attempting to keep the query experience similar (if not the same). Error handling is no different. For example, while most supported languages have the concept of Exceptions for error handling, Go does not. Yet, while using the Go driver, you can access similar methods/attributes on the error object resulting from any failed query.

Error responses

When a query fails due to query construction, permissions, or other in-database error (as opposed to an HTTP error), Fauna responds with a JSON error message. Each error message contains a top-level errors array, since a query may have failed for multiple reasons. The errors array contains "error" objects that contain the following fields:

Error field Description


A Fauna error code.


A human-readable description of the error.


An Array of FQL function names, or array offsets, identifying which portion of the query encountered the error.


An error object, containing the code, description, and position fields. Returned only when a query fails within a called UDF.

Authentication errors

When the secret provided with the query is invalid, for any reason, the response is:

  errors: [
      code: 'unauthorized',
      description: 'Unauthorized'

Query execution errors

When a query cannot be executed, the response includes a position array that indicates where in the query that the error occurred. For example:

Map(Paginate(Documents(Collection("does_not_exist"))), Lambda("X", Get(Var("X"))))
  errors: [
      position: [
      code: 'invalid ref',
      description: "Ref refers to undefined collection 'does_not_exist'"

The position field indicates that the invalid ref error occurred within the collection of documents returned from the Paginate call’s Documents function: the collection does_not_exist does not exist.


There are many different ways that Fauna queries can fail. Here is the list of exception/error types provided:

Error type Description


The client connection was aborted due to some client/OS signal that occurred.


An HTTP 400 error occurred, indicating that the query was transmitted in an incorrect HTTP request.


A query was attempted using a closed client object.


An HTTP 500 error occurred, indicating that some Fauna infrastructure encountered a problem that prevents fulfilling the request.


The wrong number of arguments was provided to a function.


An invalid value was provided as a function argument. This occurs when:

  • a document ID for a Reference is null or undefined.

  • A timezone other than Z was used in a FaunaTime value.

  • A Byte was expected but a non-bytes value was specified.


An HTTP 405 error occurred, indicating that the query was sent without using the POST method.


An HTTP 404 error occurred, indicating that the requested resource was not found.


An HTTP 403 error occurred, indicating that the query requires permissions that the current identity (associated with the secret) does not have.


An error occurred in an active stream.


An error occurred that prevented the current stream from continuing.


The current driver does not support streaming.


An HTTP 429 error occurred, indicating that the client has sent too many requests in a period of time, and is being rate limited.


An HTTP 401 error occurred, indicating that the client does not have permission to access the requested endpoint.


An HTTP 503 error occurred, indicating that some Fauna infrastructure is unavailable to service the request. It could be restarting or broken.

Accessing Exception/Error details

  q.CreateCollection({ name: 'cars' }),
  q.Abort('Reset Transaction'),
.then((ret) => console.log(ret))
.catch((err) => {
  console.error('Exception name: "%s"', err.name)
  console.error('Exception message: "%s"', err.message)
  console.error('Exception description: "%s"', err.description)
  console.error('Exception httpStatusCode: "%s"', err.httpStatusCode)
  console.error('Error code: "%s"', err.errors()[0].code)
  console.error('Error position: "%s"', err.errors()[0].position)
  console.error('Error description: "%s"', err.errors()[0].description)
  console.error('Error all errors:', err.errors())
Exception name: "BadRequest"
Exception message: "transaction aborted"
Exception description: "Reset Transaction"
Exception httpStatusCode: "undefined"
Error code: "transaction aborted"
Error position: "[ 2 ]"
Error description: "Reset Transaction"
Error all errors: [
    position: [ 2 ],
    code: 'transaction aborted',
    description: 'Reset Transaction'
Query metrics:
  •    bytesIn:   93

  •   bytesOut:   92

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    0

  •  readBytes:  802

  • writeBytes:    0

  •  queryTime: 12ms

  •    retries:    0

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!