Error codes
Status: Implemented. The
cl_resultcodes are inclight.h; the loader codes below are what the loader, the runtimes andclight checkreport. Codes marked (planned) belong to features that aren’t in the game yet.
API result codes (cl_result)
| Value | Constant | Meaning | Typical cause |
|---|---|---|---|
| 0 | CL_OK |
Success | |
| −1 | CL_E_UNKNOWN |
Unexpected internal error | Report it, with the log |
| −2 | CL_E_INVALID_ARGUMENT |
An argument is out of range or malformed | Bad identifier, negative count, NULL out-pointer |
| −3 | CL_E_INVALID_HANDLE |
The handle was never valid | Uninitialised handle, a handle of the wrong kind cast by hand |
| −4 | CL_E_STALE_HANDLE |
The object no longer exists | The entity died, the chunk unloaded, the screen closed |
| −5 | CL_E_WRONG_TYPE |
The handle is valid but the wrong kind for this call | cl_player_* on a non-player |
| −6 | CL_E_NOT_FOUND |
Lookup failed | Unknown block id, missing resource, absent memory |
| −7 | CL_E_ALREADY_EXISTS |
Duplicate registration | The same id registered twice |
| −8 | CL_E_WRONG_PHASE |
Not allowed in the current lifecycle phase | Registering after the freeze, reading a holder before it |
| −9 | CL_E_WRONG_THREAD |
Not allowed in the current thread context | A mixin helper called outside its callback’s context |
| −10 | CL_E_WRONG_SIDE |
Client API on the server or the reverse | cl_hud_* on a dedicated server |
| −11 | CL_E_PERMISSION_DENIED |
Not allowed for this mod | A capability not granted, registering outside your namespace, a file outside the mod folder |
| −12 | CL_E_BUFFER_TOO_SMALL |
The output buffer is too small. *out_len holds the size needed. |
String getters |
| −13 | CL_E_OUT_OF_MEMORY |
Allocation failed or the sandbox memory limit was reached | |
| −14 | CL_E_NOT_LOADED |
The chunk or level isn’t loaded | cl_level_get_block outside loaded chunks |
| −15 | CL_E_UNSUPPORTED |
Not available in this configuration | RmlUi overlays (as_screen = false), cancelling a target that can’t be cancelled |
| −16 | CL_E_VERSION |
Version mismatch | |
| −17 | CL_E_PARSE |
JSON, SNBT or text parse error | cl_last_error_message() has details |
| −18 | CL_E_LIMIT |
A limit was exceeded | Payload too large, the C++ lambda table full |
| −19 | CL_E_CANCELLED |
The operation was cancelled | Mod unload |
| −20 | CL_E_TIMEOUT |
Timed out | |
| −21 | CL_E_CONFLICT |
Exclusive resource already taken | The keybind id taken |
| −22 | CL_E_DEPENDENCY |
A required mod is missing | |
| −23 | CL_E_IO |
File-system error | Disk full, file locked |
| −24 | CL_E_NETWORK |
Network error | |
| −25 | CL_E_TRAPPED |
The callback trapped and was aborted (sandbox) | |
| −26 | CL_E_DISCONNECTED |
The player or connection is gone | Sending to a player who left |
| −27 | CL_E_BUSY |
The target or resource is busy | A mixin target already running for another mod |
cl_last_error_message(char* buf, size_t cap, size_t* n) returns a human-readable detail for the last failing call on this thread.
Loader errors (CLL-xxxx)
Shown on the Mods screen and in logs/latest.log. The game keeps loading when a mod fails ("critical" is accepted but not acted on yet).
| Code | Meaning |
|---|---|
| CLL-1001 | clight.mod.json missing or not valid JSON |
| CLL-1002 | The manifest fails the schema (the field is named in the message) |
| CLL-1003 | Invalid mod id |
| CLL-1004 | Duplicate mod id (two files provide the same id) |
| CLL-1005 | Invalid version string (not semver) |
| CLL-2001 | Required dependency missing |
| CLL-2002 | Dependency version out of range |
| CLL-2003 | The mod needs a newer CLight API than this engine provides |
| CLL-2004 | The mod was built for a CLight major version this engine no longer supports |
| CLL-2005 | The game version is not in the mod’s game range |
| CLL-2006 | A breaks rule matched |
| CLL-2007 | Dependency cycle |
| CLL-2010 | Warning, not an error: the mod used a deprecated function, an older Lua spelling or a renamed name. It keeps working; the warning is shown once per mod and names the replacement (ABI stability and API versioning) |
| CLL-3001 | The runtime type isn’t supported (every mod runs sandboxed: wasm, lua or data), or the WASM entry file isn’t in the mod folder |
| CLL-3002 | (retired: there are no native binaries) |
| CLL-3003 | The WASM module failed validation or compilation, the WASM runtime is unavailable, or CL_MIXIN records are malformed |
| CLL-3004 | The WASM module couldn’t be instantiated (it imports a function this engine doesn’t have) |
| CLL-3005 | (reserved) |
| CLL-3006 | (reserved) |
| CLL-3007 | The entry point failed (clight_mod_main returned an error or trapped), a call ran past its deadline, or too many traps |
| CLL-4001 | A Lua mod failed to load (a syntax error or an error in the entry script) |
| CLL-4002 | (planned) Signature invalid (the file was modified after signing) |
| CLL-4003 | (planned) Capability declined |
| CLL-5001 | (retired: there are no replace hooks) |
| CLL-5002 | (planned) Registry conflict: the same id from two mods |
| CLL-6001 | (planned) Multiplayer: required mod missing on the client |
| CLL-6002 | (planned) Multiplayer: version mismatch |
| CLL-6003 | (planned) Multiplayer: registry hash mismatch |
| CLL-6004 | (retired: there is no trust prompt) |
| CLL-7001 | Unknown mixin target (the message suggests a close name), or a mixin handler that doesn’t exist |
| CLL-7002 | Unknown point, value or call in the target, or a malformed at |
| CLL-7003 | The mixin target needs a newer CLight API |
| CLL-7004 | Cancel refused: the target or point isn’t cancellable, or it returns a value and none was set |
| CLL-7005 | Two mods overwrite the same target: the earlier one wins, the other mod’s overwrite is off (the mod keeps running) |
| CLL-7006 | Two mods redirect the same call with exclusive: as CLL-7005 |
| CLL-7007 | The target needs a permission the mod didn’t declare, or the player declined it |
| CLL-7008 | Cycle in the before / after options of the mixins on one target (priority and load order are used) |
| CLL-7009 | A mixin was turned off for the session after an error or trap (its changes were dropped) |
| CLL-7010 | A mixin never runs: another mod overwrites the target and doesn’t call the original |
| CLL-7011 | Mixin nesting limit (16) reached: the target ran without mixins |
| CLL-7012 | A Lua mixin on a PARALLEL target (worldgen worker threads) |