CandleVM Errors
CandleVM can report errors while it loads an executable and while it executes bytecode. Displayed errors use the form <type> Error: <message>. The entries below describe the errors that can occur and the messages they report.
A runtime error can be caught by Pcall, which stores it in an Error object. NewError creates a custom runtime error.
Runtime Errors
These errors are raised while CandleVM decodes or executes bytecode.
Custom
A custom error created from a message by NewError. Its message is the supplied string.
InvalidOpcode
The bytecode contains an opcode byte that CandleVM does not recognize. See the opcode reference.
InvalidValueType
A serialized value contains a type discriminator that is not a recognized Value type.
UnexpectedBytecodeEnd
CandleVM reaches the end of the bytecode while reading an opcode operand or a length-prefixed value.
InvalidJump
A jump instruction targets a bytecode position outside the valid range. The target must be at least zero and less than the bytecode length.
ValueTypeMismatch
An instruction or value conversion requires a particular Value type, but the register contains another type. The error message includes the expected and actual types.
ObjectTypeMismatch
An operation requires an Object of a particular type, but the ObjectRef points to a different object type. The message includes the expected and actual types.
ArrayTypeMismatch
A value in an Array has the wrong Value type for the operation. For example, StringFromChars requires every array element to be a Char.
InvalidNumber
A number cannot be represented as a finite CandleVM Number, or text supplied to StringToNumber cannot be parsed as a supported number. NaN and infinities are rejected.
InvalidChar
A serialized character contains a u32 value that is not a valid Unicode scalar value.
ModuleName
LoadModule requests a module name that is not present in the loaded program or its plugins.
FunctionName
LoadFunction requests a function name that does not exist in the selected module.
InvalidModuleRef
A ModuleRef contains an ID that does not identify a loaded module.
InvalidFunctionRef
A FunctionRef contains a module and function ID that do not identify a loaded function.
InvalidHeapRef
An ObjectRef contains an ID that is not present in the VM heap.
InvalidString
A byte sequence expected to contain UTF-8 is invalid. This can occur while reading executable or bytecode metadata, or converting a Buffer to a String. The loader reports the same public error type for invalid UTF-8 strings in executable metadata.
InvalidInt
A numeric value used where a non-negative integer is required is negative or not integral.
ByteLimit
A numeric value converted to a Byte is outside the range 0 through 255.
UsizeLimit
A non-negative integer is too large to fit in a platform usize.
ValueNotSerializable
Bytecode attempts to load a serialized ModuleRef, FunctionRef, or ObjectRef. These reference values cannot be encoded by LoadConst.
DivisionByZero
An arithmetic division or remainder operation uses zero as its divisor. Both positive and negative zero are treated as zero; see the arithmetic opcodes.
ArrayIndexOutOfBounds
An Array operation uses an index outside the allowed range. ArrayGet, ArraySet, and ArrayRemove require an index less than the length; ArrayInsert also permits an index equal to the length.
BufferIndexOutOfBounds
A Buffer read or write uses an index greater than or equal to the buffer length. The error message includes the requested index and length; see the buffer opcodes.
MapKeyNotFound
MapGet or MapRemove requests a key that is not present in the Map. The missing key is included in the error message.
ResourceNotFound
LoadResource requests an embedded resource ID that is not present in the loaded program.
ReadOnlyGlobal
StoreGlobal attempts to change a global that already exists as read-only. The global name is included in the error message.
Os
Wraps an operating-system error. When the wrapper has no underlying message, CandleVM reports An OS error occurred.
InvalidInput
An instruction contains an invalid runtime input that does not have a more specific error type. Current cases include a call argument count greater than the supported maximum, a closure capture count greater than the maximum, or a closure capture count that does not match its function. See calls and closures.
CallstackOverflow
A function call would exceed CandleVM's maximum call-stack depth of 1024 frames.
CallstackUnderflow
A return operation attempts to pop a call frame when the call stack is empty.
Loader Errors
These errors occur before bytecode execution while CandleVM reads the executable or loads its plugins. See the executable format and plugin documentation. Invalid UTF-8 metadata is reported as InvalidString.
InvalidMagic
The executable header does not begin with the required CAND magic bytes.
UnsupportedVersion
The executable's Candle format version is not supported by this loader. The error message includes the expected and found versions.
ModuleNameAlreadyUsed
A module has a name already used by another program or plugin module.
FunctionNameAlreadyUsed
Two functions in the same module have the same name.
ReachedModuleLimit
The program's module table exceeds the maximum number of module IDs available to the program.
ReachedPluginModuleLimit
A plugin contains too many modules to fit in the module ID range reserved for plugins.
ReachedFunctionLimit
A module contains more functions than the loader supports.
ReachedFunctionParameterLimit
A function declares more than the supported maximum of eight parameters.
ReachedFunctionCaptureLimit
A function declares more than the supported maximum of eight captured values.
ReachedResourceLimit
The executable's resource table exceeds the maximum resource count supported by the loader. The table count is encoded as u16, while the configured maximum is also u16::MAX, so this check cannot currently be triggered by a decoded count.
ReachedResourceSizeLimit
A resource exceeds the maximum size of 64 MiB.
ResourceIdAlreadyUsed
Two embedded resources use the same ID.
PluginNotFound
A plugin path supplied to the loader does not identify an existing file.
PluginNameAlreadyUsed
Two loaded plugins have the same name.
MissingPlugin
The executable requires a plugin name and version that are not present among the loaded plugins.
PluginLoad
The loader could not load a plugin from the specified path. The underlying plugin-loading error is included in the message. See the plugin documentation.
UnexpectedEndOfFile
The executable ends before the loader has finished reading the header, plugin table, module table, or resource table.