Troubleshooting

Find common symptoms, their causes, and the steps to resolve them.

Symptom	Check or correction
Script is not listed	Use Open Lua Folder, save directly in that folder with a lowercase .lua extension, then Refresh Scripts. Subfolder modules are not entry scripts.
File fails before execution	Check that it is a regular nonempty text file no larger than 1 MiB; entry symlinks and bytecode are not accepted.
Status reports a syntax error	Open the reported file and line, correct the Lua source, save, and Reload.
attempt to index a nil value for a player	A disconnected slot or absent selection can return nil; test it before reading fields.
Wrong person after a player leaves	Preserve and validate the ID/generation pair; a slot is reusable.
Overlay disappears immediately	Draw from script.on_tick(); initial/menu callback drawing is cleared before publication.
Overlay has wrong scale or position	Coordinates are pixels, not normalized 0–1 coordinates; inspect draw.screen().
Toggle changes in the menu but local state does not	control:set() does not invoke the callback; update your own state too.
Menu option no longer exists	A removed control handle is stale; do not reuse it.
Page has no rename, set, or remove method	Those are control methods; MenuPage only exposes page builders.
Callback budget exceeded	Return promptly, avoid busy loops, and spread work across timers/updates.
WAIT/native sleep fails	Use script.every() or script.after().
Native name returns nil	Check namespace casing, spelling, and leading underscores against the index.
Native argument count/type error	Match the declared prototype; a pointer argument is not an automatically allocated out-parameter.
A hash loses precision	Use an exact integer or 0x string for 64-bit bridge hashes; do not round through a floating-point number.
print fails for several values	Build one string with tostring, concatenation, or string.format.
io, os, debug, or coroutine is missing	Those standard libraries are not opened by Harmony.
require cannot find a module	Check LUA/module.lua or LUA/module/init.lua; native DLL module loading is disabled.
Timer/option/drawing limit reached	Reuse controls and callbacks; avoid registering them every update.
Social Club returns busy	The service is shared; wait and retry in a bounded way.
Network registration is unavailable	Check the corresponding availability function and wait for a stable active session.
A filter stopped after a session change	Rules are session-scoped and expire; a retained numeric rule ID is not proof it remains installed.
Observer return true does not block	Observer returns are ignored; filtering is performed by pre-registered rules before callback delivery.
Scan/patch rejected in a callback	Those operations are initial-load-only.
A memory scan result is truthy but unusable	It returns a Pointer even on failure; check pointer:is_null().
Memory/string range error	Check ownership, full bounds, page access, and string termination; do not continue with an invalid pointer.
Real names appear in a custom overlay while streaming	Your script owns its display policy; use labels such as player_<id> instead of raw identity fields.

When reporting a problem, include the Harmony build, script.api_version, script filename, relevant Status/log text, minimal source that reproduces the issue, and whether it occurred while loading, in a menu callback, or during updates. Remove real names and IDs from shared diagnostic output when they are not needed.