LSL error handling

How Lux Simple Lang raises, catches and reports errors: safe, try/else, Error, check, last_error, the format of uncaught errors, and compiler diagnostics.

Overview

Tool Syntax When to use
safe safe: ... end ignore an error and continue after the block
try/else try: ... else: ... end run a fallback when the block fails
Error() Error(Type: "message") raise your own error
check() check(condition, "message") assert a precondition, fail otherwise
last_error() last_error() text of the error that was caught

An error interrupts normal flow and propagates out of functions until a safe or try catches it. If nothing catches it, the program prints the error to stderr and exits with status 1.

safe

When a runtime error happens inside safe, the rest of the block is skipped and the program continues after end.

print "Start"
safe:
    x = 10 / 0                 # error here
    print "never printed"
end
print "Program continues"

safe hides what went wrong; inspect last_error() afterwards:

safe:
    config = readfile("config.json")
end
if last_error() != None:
    print "Could not read the configuration, using defaults."
    config = "{\"port\": 8080}"
end

safe is not a security sandbox and does not roll back files, I/O or collection changes already made.

try / else

else runs only when the try block fails; inside else, last_error() gives the error text. If try succeeds, else is skipped.

try:
    data = readfile("/etc/app/config.json")
else:
    try:
        data = readfile("config.json")
    else:
        print "Nothing loaded:", last_error()
        data = "{}"
    end
end

There is no finally block: do cleanup before end or duplicate it in else.

Error — raising your own error

Error(TypeError: "expected Int, got String")
Error(ValueError: "value must be positive")
Error(DatabaseUnavailable: "database is not reachable")

The name before the colon is any identifier you choose; the text explains what happened.

function find_user(name, database):
    if name not in database:
        Error(UserNotFound: "user '" + name + "' does not exist")
    end
    return database[name]
end

check — preconditions

check(condition, "message") raises an error (reported as CheckError in 0.10.2) when the condition is false. Division by zero raises ZeroDivisionError.

function safe_divide(a, b):
    check(b != 0, "division by zero")
    return a / b
end

Equivalent to if not condition: Error(...) end. Ideal for validating arguments.

last_error()

Returns the text of the caught error (String), or None before the first error and after a successful safe/try body (success also clears an older error, including when the body is left with return, break or continue). The text stays available in else and after a caught error; the state is per thread. Reading it does not clear it. If the handler runs another safe/try, store the text in a variable first.

Caught text looks like TypeError: sequence index must be Int at program.lsl:2:18 or ValueError: invalid Int String.

What can be caught

Runtime errors are caught. Since 0.8.2, inside safe/try and inside function bodies, unknown functions/variables, missing methods and statically detectable type or argument errors become runtime NameError / AttributeError / TypeError, so a caller can catch them. Outside functions and protective blocks they stay compile-time diagnostics.

Not caught: syntax (parse) errors, missing imports, unsupported constructs, violations of safe/sandbox rules, allocator exhaustion, operating-system signals and exit().

Uncaught errors

Since 0.9.1 an uncaught runtime error is printed in the same format as compiler errors:

error[TypeError]: sequence index must be Int, got String
 --> program.lsl:2:18
  |
2 |     return items[key]
  |                  ^~~
 help: convert the index with Int(...)

Colors follow NO_COLOR / FORCE_COLOR / TERM=dumb. The source line is shown only for .lsl files, so errors pointing into .env or configuration do not print secret values. A worker thread that dies with an uncaught error prints LSL worker error: ...; other threads and the main program continue.

Error types used by standard modules

Module Error type Meaning
json JsonError invalid JSON
os OSCommandError command failed (os.check)
process ProcessError process failed (process.check)
system PackageError, SystemError packaging / system administration error
tensor TensorShapeError, TensorIndexError, TensorLayoutError bad shape, index out of range, non-contiguous tensor
config ConfigCycleError cyclic configuration dependency
fd FileError file or socket error
built-in help() HelpError unknown help topic
X11 output X11Error display disconnected or timed out
load json

try:
    data = json.decode("{invalid json")
else:
    print "JSON parsing failed:", last_error()
    data = {}
end

Compiler diagnostics

Compile errors and warnings have codes and point at the source:

Code Meaning (examples seen in the manual and 0.10.2)
E0011 unterminated block comment
E1100 expected an expression (syntax)
E1119 comma before for in a comprehension ([0, for x in rang(3)])
E2001 unknown function/variable, wrong operand types, or a call statement without call
E2002 local variable read before it is assigned on every path
E2003 conflicting type-constraint declarations
W2004 assignment inside a function creates a local that shadows a global (use global)
E3001 library not found (load NAME): check ./NAME.lsl, or lsl search NAME / lsl install NAME
E3002 library exists but cannot be read

The compiler reports the first error it finds. lsl compile (checked mode) also rejects private __lsl_*, native and thread operations outside an unsafe: block.

How to choose

Can this error happen in normal operation?
  no  -> check()   (fail early and loudly)
  yes -> do I need to know that it failed?
           yes -> try/else
           no  -> safe (optionally last_error() for logging)