wolfhacklua API 1.1 Forum

Troubleshooting

Where to look first#

  1. The script's card on the Scripts page shows its status and, below it, the status text: the reason it failed or was stopped.
  2. The Console tab shows every line every script logged, newest last, with warnings and errors coloured. A repeated line appears once with a count.
  3. 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#

StatusMeaningWhat to do
OffInstalled but not enabled.Switch Enabled on.
RunningThe script is loaded and its callbacks run.Nothing.
ErrorIts code failed to load or run (a syntax error, or an error at load).Read the message, fix the file, press Reload.
StoppedThe 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.
IncompatibleThe 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#

MessageMeaning 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 grantedSwitch the permission on in the script's Permissions.
... which is not requested by this scriptAdd the permission to "permissions" in the manifest (or the --@permissions header) and Reload.
draw.rect can only be called while drawingdraw.* 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 nestedA card cannot contain a card.
can only be called while building a tab or a windowYou 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 drawA 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 expensiveSimplify the string pattern or shorten the subject.
net.request: 'x' is not one of the hosts this script's manifest listsAdd the host to net_hosts.
mem.write_u32: writing game memory is switched offSwitch 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 frameWrite or read less per frame; read blocks with mem.read_bytes.
this script needs 'mylib' >=2.0 but version 1.2.0 is installedUpdate 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.
  • pcall turns 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? 0xFF000000 is 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 with draw.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".

lua
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:

SituationMessageFix
Your major is newer than the overlay'sthis 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 olderhas to be portedThe API changed incompatibly; port the script.
Your minor is newer than the overlay'sthis script needs API 1.2 or newer; this build offers 1.1Update the overlay.
Same major, same or older minorrunsA 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.

API 1.1 · source docs-src/pages/help/troubleshooting.md