Troubleshooting
Where to look first#
- The script's card on the Scripts page shows its status and, below it, the status text: the reason it failed or was stopped.
- The Console tab shows every line every script logged, newest last, with warnings and errors coloured. A repeated line appears once with a count.
- The Manage tab of a selected script shows its timing, memory and strikes. Use it when a script is slow or was stopped.
An error is always one line you can read, with the file name and line number for a Lua error (main.lua:12: ...) and a short traceback underneath. Fix the first error: later ones are often consequences.
Status names#
| Status | Meaning | What to do |
|---|---|---|
| Off | Installed but not enabled. | Switch Enabled on. |
| Running | The script is loaded and its callbacks run. | Nothing. |
| Error | Its code failed to load or run (a syntax error, or an error at load). | Read the message, fix the file, press Reload. |
| Stopped | The host stopped it: five budget strikes in 20 seconds, 40 errors in 20 seconds, or it ran out of memory. | See performance; fix the cause and press Reload. |
| Incompatible | The manifest is invalid, asks for a newer API, or a dependency is missing or the wrong version. | The status text says which; see below. |
Common errors#
| Message | Meaning and fix |
|---|---|
main.lua:N: attempt to index a nil value (field 'x') | You used a value that is nil. A function returned nothing, or a table lacks that key. Check with if x then. |
main.lua:N: attempt to call a nil value (global 'foo') | The function does not exist: a typo, a function from another Lua (such as io.open), or a local function used before it was defined. |
... needs the 'data' permission, which is not granted | Switch the permission on in the script's Permissions. |
... which is not requested by this script | Add the permission to "permissions" in the manifest (or the --@permissions header) and Reload. |
draw.rect can only be called while drawing | draw.* only works inside events.on("draw"), a widget's draw, or a ui.canvas callback. |
ui.toggle must be inside ui.card(...) | Controls belong inside ui.card. |
ui.card cannot be nested | A card cannot contain a card. |
can only be called while building a tab or a window | You called a ui.* control outside the function you gave ui.tab, ui.window or ui.card. |
at most 8 tabs per script (also windows, widgets) | The limit is 8 of each. |
ui.widget{id = "my-widget" (2-48 of a-z 0-9 - _) ...} | A widget or window needs an id of 2 to 48 characters from a-z 0-9 - _, a size and a draw or body function. |
script ran past its time budget in draw | A callback took more than its budget. Do less per call or split the work with task.yield(). |
not enough memory (this script may use 32 MB) | Free tables or raise "memory_mb" (at most 96). |
pattern too expensive | Simplify the string pattern or shorten the subject. |
net.request: 'x' is not one of the hosts this script's manifest lists | Add the host to net_hosts. |
mem.write_u32: writing game memory is switched off | Switch on Let scripts write game memory on the Scripts page. Use mem.can_write() to check first. |
mem.write_u32 needs the 'memory_write' permission... | Request and grant memory_write. |
mem.write...: more than 512 memory writes in one frame / mem.read...: more than 8192 memory reads in one frame | Write or read less per frame; read blocks with mem.read_bytes. |
this script needs 'mylib' >=2.0 but version 1.2.0 is installed | Update or install the library the manifest requires. |
manifest.json is not valid JSON ... | A syntax error in the manifest: a missing comma or quote. Also check the file is UTF-8, not UTF-16. |
Checking things quickly#
- Put
log.info(...)where you suspect something and watch the Console.print(...)goes to the same place. log.info(json.encode(value, true))prints a table readably.pcallturns an error into a value you can inspect:local ok, err = pcall(f).- If a draw handler seems to do nothing, log once:
if time.frame() % 120 == 0 then log.info("draw ran") end.
Nothing shows on screen#
- Is the status Running? Is the script enabled and its handler registered at load (not inside a function that never runs)?
- Is the colour's alpha non-zero?
0xFF000000is invisible (the last byte is alpha). - Is the position on screen? Print
app.screen_size(). - Is
draw.alpha()left at a low value from earlier drawing? Reset it withdraw.alpha(1). - A widget with the menu closed is visible; a window only appears while the menu is open.
- Players missing from
data.snapshot().players: the overlay only supplies the teams whose ESP is on (game data).
Missing assets#
Textures, fonts and shaders load on worker threads and become ready a few frames later. Until then drawing them does nothing, which looks like "missing".
local logo = assets.texture("assets/logo.png")
events.on("draw", function()
if logo:failed() then
local _, why = logo:failed()
-- logged once, then skip
elseif logo:ready() then
draw.image(logo, 20, 20, 64, 64)
end
end)tex:failed() returns true and a reason. Reasons you may see: not a picture the overlay can read (PNG, JPEG, BMP, TGA up to 4096 x 4096), the picture could not be decoded, too many textures (limit 64), the script's textures would use more than 64 MB. A path that does not exist fails the same way: check the spelling and that the file is in the installed folder (Documents\Base\scripts\<id>\), not only next to your original. assets.exists(path) and assets.list(dir) show what the script can see; "data:name.png" reads from the data folder instead.
Fonts need font:ready(); an unreadable file never becomes ready. A shader that did not compile reports its error through shader:state() and in the console: script shaders may not loop, may not use # directives or resources, and are limited to 400 instructions and 8 KB.
API-version compatibility#
The API version is major.minor. The host compares your manifest's "api" with its own:
| Situation | Message | Fix |
|---|---|---|
| Your major is newer than the overlay's | this script targets API 2.0 but this build offers API 1.1 (update the overlay) | Update the overlay, or target an older API. |
| Your major is older | has to be ported | The API changed incompatibly; port the script. |
| Your minor is newer than the overlay's | this script needs API 1.2 or newer; this build offers 1.1 | Update the overlay. |
| Same major, same or older minor | runs | A newer minor only adds functions. |
Declare the lowest version that has what you use, so the script runs on as many builds as possible: the mem module needs "api": "1.1", everything else needs only "1.0". At run time use api.require(1, 1) to fail early, or api.has("mem") to check for a feature and fall back without failing. The version this documentation describes is shown in the top bar and on each entry (since 1.1).
Dependencies#
"requires": { "mylib": ">=1.0 <2" } needs another installed script or library. A missing one reads not installed; a wrong version reads needs 'mylib' ... but version ... is installed. Install or update it, then Reload.
When a script is stopped#
A Stopped script's status text names the cause. Typical fixes:
- went over its execution budget 5 times: look at the Manage tab for the slow callback. A loop that runs per frame over a large list, or text built every frame, are the usual causes.
- raised 40 errors within 20 seconds: the Console shows the repeated message. A typo in a draw handler produces one error per frame.
- out of memory: tables growing without bound (for example appending to a list every frame and never clearing it).
Resetting a script's saved data#
The script's settings and files are in Documents\Base\script-data\<id>\. Delete settings.json there (with the script switched off) to reset the saved settings.
Still stuck#
Check the gaps page: what you want may not exist yet. If it is a bug, the console text and the script's manifest.json are the information worth posting.