Lua.RuntimeException exception (Lua v1.0.1)

View Source

Raised when a Lua program fails at runtime — bad argument types, arithmetic on a non-number, indexing a nil, an explicit error() call from Lua, or any other dynamic failure inside the VM.

Exception.message/1 returns a plain, single-line, ANSI-free string — the error body plus a compact (at source:line) suffix — safe to drop into a Logger call or an error tracker. There is no :message struct field; the message is composed lazily from :original (and the semantic fields below), so there is no field that reads back nil for the common case of a wrapped VM error.

For a rich, human-readable report (location header, stack trace, suggestions, and ANSI color on a TTY) use Lua.format_exception/1 — this is what mix lua.eval prints. For structured error reporting (JSON, a UI) use to_map/2.

Fields:

  • :original — the underlying VM error term
  • :kind — the category of failure: :error (an explicit error() call), :type, :argument, :assertion, or :internal; nil for host-side API errors that don't originate from a Lua value
  • :value — the raised Lua value (per §6.1), as pcall/xpcall would hand it back; nil when there is no Lua-side value
  • :state — the internal VM state at the point of failure
  • :line — line number where the error was raised
  • :source — source name (filename or the default <eval>)
  • :call_stack — list of Lua frames at failure

Summary

Types

kind()
t()

Functions

format(e)

Renders the rich, multi-line report for this error — location header, stack trace, and suggestions — with ANSI color when IO.ANSI.enabled?/0 is true.

to_map(exception, opts \\ [])

Returns a wire-safe structured map — message, source, line, call_stack, source_context, suggestion, error_kind — with no ANSI escapes in any field. Intended for JSON payloads, structured logs, and UI-facing error reporting.

Types

kind()

@type kind() :: :error | :type | :argument | :assertion | :internal

t()

@type t() :: %Lua.RuntimeException{
  __exception__: true,
  call_stack: term(),
  kind: term(),
  line: term(),
  original: term(),
  source: term(),
  state: term(),
  value: term()
}

Functions

format(e)

@spec format(t()) :: String.t()

Renders the rich, multi-line report for this error — location header, stack trace, and suggestions — with ANSI color when IO.ANSI.enabled?/0 is true.

This is the terminal/REPL rendering mix lua.eval prints and what Lua.format_exception/1 delegates to. For the plain, single-line, log-safe string use Exception.message/1; for structured data use to_map/2.

to_map(exception, opts \\ [])

@spec to_map(
  t(),
  keyword()
) :: map()

Returns a wire-safe structured map — message, source, line, call_stack, source_context, suggestion, error_kind — with no ANSI escapes in any field. Intended for JSON payloads, structured logs, and UI-facing error reporting.

Pass :source_code to populate source_context. Wrapped VM errors delegate to their own to_map/2; host-side errors (no Lua value) return a minimal map.