Troubleshooting
Every message the mod layer can show, what causes it and how to fix it. You see them in two places:
- the MODS page: the status of each mod and the start of the reason;
- the log (the terminal the game runs in): the full text, tagged
[mods]or with your mod id.
Search this page for the words of your message. Parts in <angle brackets> change from case to case.
Statuses
Section titled “Statuses”| Status | Means |
|---|---|
active |
Loaded and running. |
disabled |
Turned off by the player in MODS. |
refused |
Written for an API level this game does not accept. |
broken |
No usable mod.json, or a damaged pack. Never runs. |
missing_dep |
A mod in requires is missing, too old, off or failed. |
conflict |
Lists, or is listed by, an active mod in conflicts; the later one is off. |
cycle |
On a requires / load_after loop. |
failed |
Raised while loading. Its data writes are undone. |
shadowed |
Another copy with the same id won. |
mod.json
Section titled “mod.json”The mod is BROKEN in the MODS list and never runs. Fix the manifest and restart.
no mod.json
Cause The folder or pack has no mod.json at its top.
Fix Put mod.json directly in the mod folder, not in a subfolder.
mod.json is not valid JSON: <parser message>
Cause A JSON syntax error: a trailing comma, a missing quote, a comment.
Fix Paste the file into any JSON checker. JSON has no comments and no trailing commas.
mod.json is not an object
Cause The file is a list or a plain value.
Fix Wrap the fields in { }.
id must match [a-z][a-z0-9_]{1,31}
Cause Upper case, a dash, a leading digit, or too long.
Fix Use lower case letters, digits and _, starting with a letter: my_first_mod.
id '<id>' is reserved
Cause The id is one of nukeislands base game forge mod mods.
Fix Pick another id.
name must be 1-40 characters
Cause name is missing, empty or too long.
Fix Give a short display name.
version must look like 1.2.3
Cause version is missing or not three numbers (1.0, v1.0.0, 1.0.0-beta).
Fix Write exactly MAJOR.MINOR.PATCH, like 1.0.0.
api_version must be a whole number >= 1
Cause api_version is missing, text, or below 1.
Fix Write "api_version": 1 (a number, no quotes).
requires must be an object { modId = "min version" }
Cause requires is a list.
Fix Write "requires": { "other_mod": "1.0.0" }.
requires.<id> must be a version like 1.0.0
Cause A dependency’s minimum version is not MAJOR.MINOR.PATCH.
Fix Use a full version: "1.0.0", not "1" or ">=1.0".
load_after must be a list of mod ids (or conflicts)
Cause Not a list, or an entry is not a valid mod id.
Fix Write ["some_mod"].
priority must be a whole number between -1000 and 1000
Cause Out of range or a fraction.
Fix Use a whole number from -1000 to 1000.
side must be both, server or client
Cause A typo in side.
Fix Use both, server or client, or leave it out.
entry must be a relative path inside the mod
Cause entry is absolute, has .. or a backslash.
Fix Use a path like src/main.luau.
overrides must be true or false
Cause overrides is text.
Fix Write true or false without quotes.
unknown field '<name>' ignored (a note, not an error)
Cause A field this game does not know, or a typo (requries).
Fix Check the spelling. Newer fields from a newer game are ignored on purpose.
the mod names itself in requires/conflicts/load_after; ignored (a note)
Cause Your own id is in one of those lists.
Fix Remove it.
needs mod API <n>, this game has <m>. Update the game or the mod.
Cause api_version is higher than this game supports. Status REFUSED.
Fix Update the game, or set api_version to the game’s level if your mod does not use anything newer.
built for mod API <n>, which this game no longer supports (oldest: <m>)
Cause The mod targets an API level the game dropped. Status REFUSED.
Fix Port the mod to the current API and raise api_version.
built for mod API <n>, this game has <m> (a warning)
Cause Older but still supported. The mod loads.
Fix Nothing urgent. Raise api_version once you have checked the mod on the new API.
Load order and dependencies
Section titled “Load order and dependencies”The mod is switched off before it runs. Nothing of it applies.
turned off in the mods list
Cause The player switched the mod off. Status DISABLED.
Fix Turn it on in MODS and restart.
duplicate id; <id> <version> is newer (<key>)
Cause Two copies of the mod. This one is older. Status SHADOWED.
Fix Delete the old copy.
duplicate id; <id> <version> is kept (<key>)
Cause Two copies with the same or a higher version elsewhere. Status SHADOWED. A folder wins over a pack of the same version.
Fix Keep one copy. If you are testing a pack, remove the folder.
needs <id> <version> or newer: not installed \| turned off \| not usable (<status>)
Cause A mod in requires is missing, off or broken. Status MISSING_DEP.
Fix Install or turn on the other mod, or fix it first.
needs <id> <version> or newer, found <version>
Cause The other mod is too old.
Fix Update it, or lower the version in your requires.
conflicts with <id> (it loads first and stays)
Cause One of the two lists the other in conflicts. The one that loads later is off. Status CONFLICT.
Fix Run one or the other. To pick which stays, reorder them in MODS.
dependency cycle among: <ids>
Cause requires / load_after form a loop (a after b, b after a). Status CYCLE.
Fix Remove one edge of the loop.
needs <id>, which failed to load
Cause Your dependency raised while loading.
Fix Fix the other mod; its own reason is in the MODS list.
Data files and data calls
Section titled “Data files and data calls”The mod is FAILED: its data writes are undone, and mods that require it are switched off. The reason names the file, kind, id and field.
data/<kind>.json: not valid JSON (<parser message>)
Cause A syntax error in a data file.
Fix Check commas and quotes. JSON has no comments.
strings/<lang>.json: not valid JSON
Cause A syntax error in a strings file.
Fix It must be one object of "key": "text" pairs.
data/<kind>.json: unknown key '<key>' (use add, patch, replace, remove)
Cause A top-level key other than the four operations, often a record id written at the top.
Fix Wrap records in "patch": { ... } (or add, replace, remove).
unknown data kind '<kind>'. Known: <kinds>
Cause The file name or the kind argument is not a data kind. data/ship.json instead of ships.json is the usual one.
Fix Use a kind from the reference: the file name is the kind.
id must be text
Cause A record id is not a string, or is longer than 48 characters.
Fix Pass the id as text: "12", not 12, for tiers.
<kind> has one record, id 'main'
Cause Single-record kinds (economy, arsenal, bot_tuning, map, minis) only have main.
Fix Write "patch": { "main": { ... } }.
bad id '<id>' for <kind>
Cause The id breaks the kind’s id rule (upper case, a dash, a leading digit…).
Fix See the kind’s page for its id rule.
record must be a table
Cause A record is a plain value.
Fix A record is an object of fields.
<kind>.<id>: unknown field '<field>'
Cause A typo, or a field this kind does not have.
Fix Check the field list on the kind’s page.
<kind>.<id>.<field> cannot be removed
Cause $remove / mod.REMOVE on a required field.
Fix Only optional fields can be removed. Set a value instead.
<kind>.<id>.<field>: <problem>
Cause A value has the wrong type or is out of range. The problem is one of the lines below.
Fix Fix the value; the reference lists every field’s type and range.
expected a number
Cause Text or a boolean where a number goes ("cost": "cheap", "cost": "1500").
Fix Write the number without quotes.
expected a whole number
Cause A fraction in a whole-number field.
Fix Round it.
out of range (<min> to <max>)
Cause The value is outside the field’s range. Values are checked, not clamped.
Fix Stay inside the range shown.
expected text of 1-<n> characters
Cause Empty or too long text.
Fix Shorten it, or use "@key" to point into your strings (the looked-up text is cut to fit).
expected true or false
Cause "true" in quotes, or 1.
Fix Write true or false.
expected one of <values>
Cause Not one of the allowed values.
Fix Pick a listed value.
expected { r, g, b } with 0-255 whole numbers
Cause A colour as text ("#ff0000"), with alpha, or out of range.
Fix Write [255, 170, 60].
expected a list of text
Cause Not a list, an empty entry, an entry over 120 characters, or too few or many entries.
Fix Write ["one", "two"].
unknown entry '<x>' (known: <values>)
Cause A list entry outside the allowed set, such as a biome name.
Fix Use only the listed names.
expected an object of numbers
Cause A map field (w, build, req, battery_at) is not an object.
Fix Write { "factory": 2 }.
expected { name = number } entries
Cause A map entry is negative, not a number, or a fraction where whole numbers go.
Fix Use non-negative numbers.
expected a list of numbers 0 to 100
Cause set_bonus has a bad entry or the wrong length.
Fix 1 to 6 numbers from 0 to 100.
expected { fewest, most } with fewest at least 1
Cause A bot salvo is not two numbers, or fewest is 0 or above most.
Fix Write [2, 4].
expected { stat = launches\|blocked\|..., at = number, text = string (30 max) }
Cause A superweapon milestone is missing a part, names an unknown stat, or its text is over 30 characters.
Fix Write { "stat": "bestTier", "at": 6, "text": "FIRST FLARE" }.
expected a table
Cause A free-form table field got a plain value.
Fix Pass a table.
<kind>.<id>: missing required field '<field>'
Cause add or replace without every required field.
Fix Each kind’s page lists the fields required when adding.
<kind> records cannot be added (api 1); override an existing one with patch
Cause The kind is change-only (ships, buildings, tiers, variants, outposts…).
Fix Patch an existing record. New ships or buildings need code, not data.
<kind>.<id> already exists (base game \| added by <mod>). Use patch to change it
Cause add with an id that is taken.
Fix Use patch, or pick a new id.
<kind>.<id> does not exist
Cause patch, replace or remove on an id that is not there. Often a typo, or a mod that removed it loaded first.
Fix Check the id in the kind’s base records table.
<kind>.<id>: replace is only for kinds that can be added; use patch
Cause replace on a change-only kind.
Fix Use patch.
<kind> records cannot be removed
Cause Only upgrades and strings allow remove.
Fix For a superweapon, patch enabled to false.
unknown operation <op>
Cause An internal operation name; you should not see it.
Fix Report it with your mod attached.
<kind>.<id>: tables with a metatable are not accepted
Cause You passed a table with a metatable (a class instance, a proxy).
Fix Pass plain tables.
<kind>.<id>: table nested too deep
Cause More than 8 levels of tables.
Fix Flatten the data.
<kind>.<id>: table too large or with odd keys
Cause Over 5000 entries, or keys that are not text or numbers.
Fix Use text or number keys; split big data.
<kind>.<id>: a function is not data (or userdata, thread, buffer, vector)
Cause A function or other non-data value inside a record.
Fix Records hold numbers, text, booleans and tables only.
<kind>.<id>: <copy problem>
Cause The record could not be copied; the problem is one of the four lines above.
Fix See above.
Scripts and require
Section titled “Scripts and require”The script raised while loading. The mod is FAILED and everything it did is undone.
entry file '<path>' is missing
Cause The manifest names an entry that is not in the mod.
Fix Fix the path or add the file. With no entry and no main.luau the mod is data-only, which is fine.
cannot read <file>
Cause The file is listed but could not be read (a damaged pack).
Fix Rebuild the pack.
mod.exports was removed
Cause Your script set mod.exports to nil.
Fix Add fields to mod.exports; do not replace or remove it.
a source file holds binary code
Cause A .luau file starts with compiled bytecode.
Fix Ship bytecode as .luauc, or build the pack with --bytecode.
require: '<path>' is not a file in this mod (mods can only require their own files)
Cause A typo, a game module, or a path outside your folder.
Fix Require your own files with ./name. Game modules are not reachable: use mod.
require: cycle at <file>
Cause Two of your modules require each other.
Fix Move the shared part to a third module.
require: cannot read <file>
Cause The module could not be read.
Fix Rebuild the pack.
require: <compile error>
Cause A syntax error in a module.
Fix The message has the file and line.
bad argument #1 to 'setmetatable' (table expected)
Cause setmetatable on something that is not a table.
Fix Only tables take a metatable in the sandbox.
data is read-only once the game has started; register it while the mod loads
Cause mod.data.add/patch/... inside an event handler, timer or UI callback.
Fix Do every data write at the top level of your script, while it loads.
unknown event '<name>'
Cause A typo in mod.on, or an event this game does not have.
Fix Use a name from the events table.
event handler must be a function
Cause mod.on("tick", nil) or a value instead of a function.
Fix Pass a function.
While the game runs
Section titled “While the game runs”Logged as warnings with your mod id. The game keeps running.
error in '<event>' handler: <error>
Cause Your handler raised. It counts toward the switch-off.
Fix The message has the line. Guard against nil payload fields.
'<event>' handler switched off after 5 errors
Cause Five errors in one handler.
Fix Fix the error; the handler stays off until the next start.
'<event>' handler took <n> ms (budget 4 ms)
Cause One slow run. Three in a row switch it off.
Fix Do less per event: cache lookups, spread work over ticks.
'<event>' handler switched off: over budget 3 times in a row
Cause Three slow runs in a row.
Fix Make the handler cheaper. frame handlers run every frame.
timer error: <error>
Cause A timer callback raised. After 5 errors the timer stops.
Fix The message has the line.
on_plan left a list missing or odd; ignored
Cause Your plan hook replaced or removed knocks, destroy or scorch, or gave it a metatable.
Fix Edit the lists in place: remove with list[i] = nil from the end, or table.remove.
on_plan error: <error>; plan unchanged
Cause Your plan hook raised. The strike runs as planned.
Fix The message has the line.
ui '<id>' error: <error>
Cause A UI draw or click callback raised. Three errors switch it off.
Fix The message has the line.
ui '<id>' took <n> ms (budget 3 ms)
Cause A slow draw callback.
Fix Draw less; compute text in a timer, not every frame.
ui '<id>' switched off: over budget
Cause Over 3 ms for 30 frames in a row.
Fix Make the callback cheaper.
ui '<id>' switched off after 3 errors
Cause Three errors in one UI callback.
Fix Fix the error; restart the game.
applying mod data failed: <error>
Cause The game could not take back the merged data. The game keeps what was applied.
Fix Report it with the mod set attached.
ready failed: <error>
Cause Firing ready failed.
Fix Report it with the mod set attached.
Cancelled by a mod (on screen)
Cause A weapon_fire handler returned false.
Fix Intended. If not, check which mod listens to weapon_fire.
superweapons.<id>: base '<base>' not found; skipped
Cause The base weapon is not in this build.
Fix Use one of the six bases.
upgrades.<id> needs '<node>', which does not exist; it stays locked
Cause req names a node that is gone (removed, or a typo).
Fix Fix the node id in req.
upgrades.<id> uses stat '<stat>' the game does not know
Cause A stat the game’s upgrade code does not read.
Fix Use a stat from the upgrades page.
<kind>.<id>: <reason> (skipped) (a note)
Cause One of your writes stopped applying after a mod that loaded earlier failed and was undone.
Fix Fix the failed mod, or stop depending on what it added.
Sprites and sounds
Section titled “Sprites and sounds”Logged as warnings. The asset is skipped; the mod still runs.
sprite '<name>' skipped: this build cannot decode images
Cause A build without the PNG decoder.
Fix Use a regular game build.
sprite '<name>' skipped: not a PNG of at most 64x64
Cause Not a PNG, or bigger than 64x64.
Fix Export a PNG up to 64x64.
sound '<file>' could not be loaded
Cause The file is not a readable Ogg Vorbis or WAV.
Fix Re-export as .ogg (Vorbis) or 16-bit .wav.
replaces the game sound '<name>' (info)
Cause Your sound has the name of a game sound.
Fix Intended if you meant to replace it; otherwise rename the file.
<sprites\|audio> '<name>': <mod> and <mod> both provide it (<mod> wins) (conflict)
Cause Two mods replace the same game sound.
Fix Rename one, or accept that the later mod wins.
<kind>.<id>.<field>: <mod> sets <a>, then <mod> sets <b> (<mod> wins) (conflict)
Cause Two mods set the same field.
Fix Reorder in MODS, or add load_after so the right one wins.
Saves and co-op
Section titled “Saves and co-op”Never blocks single player. Co-op refuses to join until both sides match.
Save used <id> <version>, which is not active now
Cause The save was made with a mod that is off or gone. Its saved data is kept unchanged.
Fix Nothing needed. Turn the mod back on to get its data back.
Save used <id> <version>, now <version>
Cause The mod was updated since the save.
Fix Nothing needed, unless the new version reads its save differently.
<id> <version> was not active when this save was made
Cause A mod added since the save.
Fix Nothing needed.
could not write mod save data: <error>
Cause Writing slotN/mods.json failed (disk full, permissions).
Fix Check the save folder.
Mod mismatch: <differences> (here = host)
Cause Co-op needs the same mods at the same versions in the same form on both sides.
Fix Install the same files on every machine. A folder and a pack of the same mod do not match.
<id> <version> is missing on the other side
Cause Part of a mismatch: the mod is here, not there.
Fix Install it on the other machine, or turn it off here.
<id>: <version> here, <version> there
Cause Different versions.
Fix Update both to the same version.
<id> <version>: files differ
Cause Same id and version, different files (or folder against pack).
Fix Copy the exact same mod to both machines.
<id> <version> is not installed here
Cause The other side has a mod you lack.
Fix Install it.
.nkp packs
Section titled “.nkp packs”The pack is listed as broken with this reason and never runs. Rebuild it with forge pack build.
not an NKPK file
Cause A .nkp that is not a pack (renamed zip, truncated download).
Fix Rebuild with forge pack build.
header checksum mismatch
Cause The pack is damaged.
Fix Download or build it again.
table checksum mismatch
Cause The pack is damaged.
Fix Download or build it again.
data checksum mismatch (file damaged)
Cause The pack is damaged.
Fix Download or build it again.
format version <n> is newer than this game reads (<m>)
Cause Built by a newer forge.
Fix Update the game, or build with this game’s forge.
truncated
Cause The file is cut short.
Fix Copy it again.
Bad arguments to mod calls
Section titled “Bad arguments to mod calls”A call with a wrong argument raises an error that names the problem. While loading, that fails the mod. In a handler or callback it ends that call and counts toward the switch-off. These are the messages, by call; the API reference has the full rules.
| Call | Message |
|---|---|
mod.after |
seconds must be 0.05 to 86400 |
mod.after |
callback must be a function |
mod.audio.play |
name must be text |
mod.data.add |
data is read-only once the game has started; register it while the mod loads |
mod.data.add |
kind must be text |
mod.data.add |
id must be text |
mod.data.patch |
data is read-only once the game has started; register it while the mod loads |
mod.data.remove |
data is read-only once the game has started; register it while the mod loads |
mod.data.replace |
data is read-only once the game has started; register it while the mod loads |
mod.every |
seconds must be 0.05 to 86400 |
mod.every |
callback must be a function |
mod.fx.blast |
x and y must be numbers (map pixels) |
mod.fx.flash |
alpha must be a number |
mod.fx.shake |
amount must be a number |
mod.game.give_charge |
unknown superweapon ' |
mod.game.give_charge |
n must be a whole number |
mod.game.toast |
toast text must be 60 characters or fewer |
mod.json.decode |
json.decode expects text |
mod.json.decode |
json.decode: |
mod.json.encode |
json.encode: only plain data (numbers, text, booleans, tables) |
mod.on |
unknown event ' |
mod.on |
options must be a table |
mod.on |
priority must be a number |
mod.read |
bad path |
mod.save.set |
key must be short text |
mod.save.set |
save.set: only plain data, 6 levels deep, 2000 entries |
mod.sprite |
name must be text |
mod.ui.button |
label is required (12 characters or fewer) |
mod.ui.button |
must be text of |
mod.ui.button |
on_click must be a function |
mod.ui.panel |
title is required (20 characters or fewer) |
mod.ui.panel |
w must be 60 to 260 |
mod.ui.panel |
h must be 40 to 180 |
mod.ui.widget |
expected a plain table of options |
mod.ui.widget |
expected a table of options |
mod.ui.widget |
id must be [a-z][a-z0-9_]* |
mod.ui.widget |
anchor must be top_left, top_right, bottom_left or bottom_right |
mod.ui.widget |
w must be 8 to 160 |
mod.ui.widget |
h must be 8 to 80 |
mod.ui.widget |
draw must be a function |
mod.ui.widget |
visible must be a function |
mod.ui.widget |
order must be a number |
mod.ui.widget |
register UI while the mod loads |
mod.ui.widget |
' already used by this mod |
mod.use |
' is not in requires or load_after |
mod.weapons.on_plan |
register on_plan hooks while the mod loads |
mod.weapons.on_plan |
on_plan expects a function |
mod.weapons.on_plan |
unknown superweapon ' |