Skip to content

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 '