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, review the 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

code

A Fauna error code.

description

A human-readable description of the error.

position

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

cause

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: [
        'collection',
        'paginate',
        'documents'
      ],
      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.

Exceptions/Errors

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

Error type Description

AbortError

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

BadRequest

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

ClientClosed

A query was attempted using a closed client object.

InternalError

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

InvalidArity

The wrong number of arguments was provided to a function.

InvalidValue

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.

MethodNotAllowed

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

NotFound

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

PermissionDenied

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

StreamError

An error occurred in an active stream.

StreamErrorEvent

An error occurred that prevented the current stream from continuing.

StreamsNotSupported

The current driver does not support streaming.

TooManyRequests

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

Unauthorized

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

UnavailableError

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

client.query([
  q.CreateCollection({ name: 'cars' }),
  q.Now(),
  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!