Troubleshooting
Where to look
- Mods → your mod shows the mod's state and, if it isn't running, why: a missing dependency, permissions waiting for review, a game version outside its range, or the error that stopped it. The Problems filter shows only mods with something wrong. The states are explained in Installing mods.
- The script editor lists errors under Problems, marks the lines in your files, and follows the mod's log in its Log tab.
/mods.log your.mod-idin the developer console shows its recent log with files and lines.theonaris-mod validatecatches most problems before the game runs anything.- The game's log file,
Player.login%USERPROFILE%\AppData\LocalLow\Ivyture\Project Avion, contains every mod line, prefixed[mod your.mod-id client]or[mod your.mod-id server].
Common problems
| Symptom | Likely cause |
|---|---|
| The mod isn't in the list | mod.json is not at the top of the folder or zip, or the zip holds a folder that holds the mod. |
| "Waiting for its permissions to be reviewed" | It asks for medium or high risk permissions: open it in Mods and press Review permissions. |
attempt to index a nil value — ui is only available in client scripts | That module doesn't exist on this side or in this situation. ui, world, effects, input and camera exist only in client scripts, net and players only in a session, and a module whose permission is undeclared is still present but refuses calls. Test if ui then first; mod.whyUnavailable("ui") says why. |
… is only available in client scripts. | A client-only function, such as audio.play, called from a server script (or the other way round). Move the call to the right script, or send a message. |
Block has no field 'positon' (did you mean 'position'?) | A typo in a field or function name. The API is strict: unknown names are errors, not nil. Use mod.has("module.name") to test for optional features. |
… is deprecated; use … instead (warning) | An old name still works but has been renamed. Switch to the new one. |
unknown field 'x' is ignored (warning) | An options table or map file has a field the game does not know, often a typo; the message suggests the nearest real one. |
needs the 'world' permission | Add the permission to mod.json and reload. |
This Block no longer exists. | You kept a handle to something that went away. Check :isValid() first. |
| "timer took 12.3 ms" warnings | A callback is too slow. Spread the work with task.spawn and task.wait. |
| "stopped after 5 aborted or refused calls" | Something keeps hitting the 250 ms limit or a permission refusal. Fix the loop, then reload. |
| A picture or sound "is not in this mod" | A path problem: script paths start at the mod root, paths inside .uxml, .uss and content JSON are relative to that file, and / starts at the root. Letter case matters on other systems. |
| A block has no texture | texture or the model's texture path is wrong; the log names the missing file. |
| Map objects are mirrored | Model files are right-handed and the game mirrors Z. See coordinates. |
| Players can't join, "download declined" | They declined the download, or the mod is over the download limits. |
/mods.reload refused | Other players are connected. Reload when alone or in the menu. |
| Saving in the script editor does not reload the mod | The status bar says why: Hot reload is off, the mod is off or waiting for consent in Mods, or other players are connected. |
| "Only the host can run code in mods" | You joined someone else's game. Running code works when you host or play alone. |
| "… is not running on the server side here" | The mod's server copy is not running: there is none outside a session, or the mod is off or stopped. Start a game (single player counts), check the mod in Mods, or run on Client. |
| Your mod changed nothing after you switched it on | Switching mods on and off waits for Apply changes in Mods. |
Validator messages
Every message has a code. Errors stop the mod from loading, and warnings don't.
Manifest (manifest.*)
| Code | Meaning and fix |
|---|---|
invalid-json, not-object, too-large | mod.json is not a JSON object, or is over 256 KB. The message has the line. |
missing-field, wrong-type, too-long, too-many | A required field is missing, has the wrong type, or is over its limit. See mod.json. |
unsupported-format | format must be 1. |
bad-id, bad-version, empty-name | The id must look like yourname.modname; the version must be semantic (1.0.0). |
bad-game-range, bad-range, bad-api | A version range or api value is not valid. |
bad-entry, bad-icon, icon-missing, bad-homepage, bad-tag | An entry script path, icon (must be a .png), homepage (https://) or tag is not valid. |
entry-side-mismatch | For example "side": "client" with a server script that will never run. |
local-server-code | "network": "local" with a server script, which never runs on other people's servers. |
bad-dependency-id, dependency-twice, self-dependency | Fix the relationship lists. |
bad-permission, unknown-permission | Misspelled or unknown permission. Check the list. |
bad-setting-key, duplicate-setting, bad-setting-default, bad-setting-range, bad-setting-option, choice-without-options, bad-value, out-of-range | A setting's key, default, range or options are invalid. |
bad-content-type, bad-content-path | A content type name or file pattern is invalid. |
unknown-key | A key the game doesn't know, usually a typo. The message suggests the right one. |
Files and packages (content.*, package.*)
| Code | Meaning and fix |
|---|---|
content.missing-manifest | No mod.json at the root. |
content.forbidden-file | An executable or foreign script. Remove it: it can never be in a mod. |
content.unknown-file | A file type mods can't contain. Ignored in folders, an error in packages. |
content.file-too-large, content.too-large, content.too-many-files | Over a size limit. |
content.case-collision | Two paths differ only by letter case, which breaks on Linux and macOS. |
entry.missing | An entry script named in mod.json does not exist. |
content.no-match | A content pattern matches no files. |
content.not-json, content.not-object, content.bad-id, content.duplicate-id | A content definition is not a JSON object, has a bad or missing id, or repeats one. |
content.missing-file, content.bad-path, content.url | A file a definition names doesn't exist (the message says where it looked, and whether you meant /…), can't be used, or is a web address. |
content.unknown-type | A content type this game doesn't have. |
content.unreadable, mod.unreadable | A file couldn't be read. |
package.invalid-zip, package.unsafe-entry, package.duplicate-entry, package.compression-ratio, package.too-large, package.too-many-files, package.file-too-large, package.unreadable | The zip is broken, contains unsafe paths or a suspiciously compressed file, or is over a limit. Repack it with theonaris-mod pack. |
File contents
| Code | Meaning and fix |
|---|---|
lua.syntax | A script doesn't compile. The message has the line. |
lua.unavailable | Uses a global the sandbox doesn't have (io, loadstring, debug…). See Scripting. |
json.invalid | Not valid JSON. |
ui.invalid, ui.warning | A .uxml isn't valid XML, or uses an unknown element or attribute (with a suggestion). |
ui.missing-style, ui.missing-picture, ui.bad-picture | A <Style src> or Image src names a file that doesn't exist, relative to the .uxml. |
style.invalid, style.warning | A .uss problem, such as an unknown property (with a suggestion). |
style.missing-picture, style.bad-picture | A url(…) names a missing file, relative to the .uss. |
image.invalid | Not a readable PNG or JPEG, the wrong format for its extension, or too large. |
audio.invalid, video.invalid | The contents don't match the extension, or the WAV encoding isn't supported. |
model.invalid, model.missing-texture | The model can't be read (the message says why), or a texture it names is missing. |
Still stuck?
Take the closest example and change it one step at a time, reloading as you go. When something breaks, the last step is the cause.