Reference / Built-in modules reference / Module box / Submodule box.error
Reference / Built-in modules reference / Module box / Submodule box.error

Submodule box.error

Submodule box.error

Overview

The box.error function is for raising an error. The difference between this function and Lua’s built-in error function is that when the error reaches the client, its error code is preserved. In contrast, a Lua error would always be presented to the client as ER_PROC_LUA.

Index

Below is a list of all box.error functions.

Name Use
box.error() Throw an error
box.error.last() Get a description of the last error
box.error.clear() Clear the record of errors
box.error.new() Create an error but do not throw
box.error.set() Set an error as box.error.last()
error_object.prev Return the previous error
error_object.set_prev() Set the previous error
box.error{reason = string[, code = number]}

When called with a Lua-table argument, the code and reason have any user-desired values. The result will be those values.

Parameters:
  • reason (string) – description of an error, defined by user
  • code (integer) – numeric code for this error, defined by user
box.error()

When called without arguments, box.error() re-throws whatever the last error was.

box.error(code, errtext[, errtext ...])

Emulate a request error, with text based on one of the pre-defined Tarantool errors defined in the file errcode.h in the source tree. Lua constants which correspond to those Tarantool errors are defined as members of box.error, for example box.error.NO_SUCH_USER == 45.

Parameters:
  • code (number) – number of a pre-defined error
  • errtext(s) (string) – part of the message which will accompany the error

For example:

the NO_SUCH_USER message is “User '%s' is not found” – it includes one “%s” component which will be replaced with errtext. Thus a call to box.error(box.error.NO_SUCH_USER, 'joe') or box.error(45, 'joe') will result in an error with the accompanying message “User 'joe' is not found”.

Except:whatever is specified in errcode-number.

box.error() accepts two sets of arguments:

  • error code and reason (box.error{code = 555, reason = 'Arbitrary message'}), or
  • error object (box.error(err)).

In both cases the error is promoted as the last error.

Example:

tarantool> e1 = box.error.new({code = 111, reason = "Сause"})
---
...
tarantool> box.error(e1)
---
- error: Сause
...
tarantool> box.error{code = 555, reason = 'Arbitrary message'}
---
- error: Arbitrary message
...
tarantool> box.error()
---
- error: Arbitrary message
...
tarantool> box.error(box.error.FUNCTION_ACCESS_DENIED, 'A', 'B', 'C')
---
- error: A access denied for user 'B' to function 'C'
...
box.error.last()

Returns a description of the last error, as a Lua table with five members: “line” (number) Tarantool source file line number, “code” (number) error’s number, “type”, (string) error’s C++ class, “message” (string) error’s message, “file” (string) Tarantool source file. Additionally, if the error is a system error (for example due to a failure in socket or file io), there may be a sixth member: “errno” (number) C standard error number.

rtype: table

box.error.clear()

Clears the record of errors, so functions like box.error() or box.error.last() will have no effect.

Example:

tarantool> box.error{code = 555, reason = 'Arbitrary message'}
---
- error: Arbitrary message
...
tarantool> box.schema.space.create('#')
---
- error: Invalid identifier '#' (expected letters, digits or an underscore)
...
tarantool> box.error.last()
---
- line: 278
  code: 70
  type: ClientError
  message: Invalid identifier '#' (expected letters, digits or an underscore)
  file: /tmp/buildd/tarantool-1.7.0.252.g1654e31~precise/src/box/key_def.cc
...
tarantool> box.error.clear()
---
...
tarantool> box.error.last()
---
- null
...
box.error.new(code, errtext[, errtext ...])

Create an error object, but doesn’t throw it as box.error() does. This is useful when error information should be saved for later retrieval. To set an error as the last explicitly use box.error.set().

Parameters:
  • code (number) – number of a pre-defined error
  • errtext(s) (string) – part of the message which will accompany the error

Example:

tarantool> e=box.error.new{code=5,reason='A',type='B'}
---
...
tarantool> e:unpack()
---
- code: 5
  base_type: CustomError
  type: B
  custom_type: B
  message: A
  trace:
  - file: '[string "e=box.error.new{code=5,reason=''A'',type=''B''}"]'
    line: 1
...
tarantool> box.error.last()
---
- nil

Beginning in version 2.4.1 there is a session_settings setting which affects structure of error objects. If error_marshaling_enabled is changed to true, then the object will have the MP_EXT type and the MP_ERROR subtype. Using the binary protocol, in the body of a packet that the server could send in response to box.error.new(), one will see: the encoding of MP_EXT according to the MessagePack specification (usually 0xc7), followed by the encoding of MP_ERROR (0x03), followed by the encoding of MP_ERROR_STACK (0x81), followed by all of the MP_ERROR_STACK components (MP_ARRAY which contains MP_MAP which contains keys MP_ERROR_MESSAGE, MP_ERROR_CODE, etc.) that are described and illustrated in section Binary protocol – responses for errors – extra. The map field for error object “type” will have key = MP_ERROR_TYPE, the map field for error object “code” will have key = MP_ERROR_CODE, the map field for error object “message” will have key = MP_ERROR_MESSAGE.

box.error.set(error object)

Set an error as the last system error explicitly. Accepts an error object and makes it available via box.error.last().

Example:

tarantool> err = box.error.new({code = 111, reason = "cause"})
---
...
tarantool> box.error.last()
---
- error: '[string "return tarantool> box.error.last()"]:1: attempt to compare two
    nil values'
...
tarantool> box.error.set(err)
---
...
tarantool> box.error.last()
---
- cause
...
object error_object

Errors can be organized into lists. To achieve this, a Lua table representing an error object has .prev field and e:set_prev(err) method.

error_object.prev

Return a previous error, if any.

error_object:set_prev(error object)

Set an error as the previous error. Accepts an error object or nil.

Example:

tarantool> e1 = box.error.new({code = 111, reason = "some cause"})
---
...
tarantool> e2 = box.error.new({code = 111, reason = "cause of cause"})
---
...
tarantool> e1:set_prev(e2)
---
...
tarantool> e1.prev
---
- cause of cause
...

Cycles are not allowed for error lists:

tarantool> e2:set_prev(e1)
---
- error: 'builtin/error.lua:147: Cycles are not allowed'
...

Setting the previous error does not erase its own previous members:

-- e1 -> e2 -> e3 -> e4
e1:set_prev(e2)
e2:set_prev(e3)
e3:set_prev(e4)
e2:set_prev(e5)
-- Now there are two lists: e1->e2->e5 and e3->e4

The iProto protocol also supports stacked diagnostics. See details in Binary protocol – responces for errors – extra.