Troubleshooting

Troubleshooting

Start with the symptom you can see. Fix one issue, save your files, and restart before checking again. For the first exercise, compare your files with Tutorial 00.

Find the error

On desktop, press F10 in the game to open the mod manager. Select the mod; a failed mod offers VIEW ERROR... The manager's ERRS tab shows reported loader errors; NO ERRORS means that feed is empty, not that every possible gameplay action has been tested. If you changed enablement there, use APPLY & RESTART when offered.

The launcher's MODS panel also shows installation, dependency, and target problems. A listed mod may still be disabled or waiting for another file. Use Show for to check the game you are actually launching.

Write down the mod ID, field/file name, and first error message. The first error often explains later messages. A screenshot of the relevant error can help when you ask the mod author for help; do not substitute a guess for the actual message.

The mod is not listed

Check the folder structure. manifest.json must be directly inside the mod folder, not inside another accidental copy of it:

mods/my_first_mod/manifest.json       correct
mods/my_first_mod/main.lua            correct
mods/my_first_mod/my_first_mod/...    one folder too deep

Show extensions in your file manager and remove an accidental .txt suffix. Check the default mod locations. Use one copy of a mod ID so that an old copy in another search location cannot hide your edits. Restart after creating a new folder.

For a downloaded mod, prefer Import mod .zip in the launcher. A source archive may contain a whole repository rather than an installable mod.

The mod is listed but not running

Row or symptom	Next step
Disabled	Enable it for the selected game and restart.
Unsupported game / target	Use the game the author supports. Do not treat a forced override as proof of compatibility.
Missing dependency	Install the required mod/version listed in the error.
Required import missing	Use the row's import control for the file specified by the author.
Experimental	Read the mod's notes and explicitly enable it if you intend to try it.
Staged changes	Apply the changes and restart.
Load error	Open the error details and check the file/field they name.

JSON or Lua syntax errors

A syntax error means the text is not in the format the language expects. It can happen before any mod behavior runs.

File	Common fix
manifest.json	Use straight double quotes; commas between fields; no comma after the last field; matching { }. JSON has no Lua comments.
main.lua	Keep return function(mod) and its closing end; close strings, parentheses, and tables. Put an insertion inside the entry function.
Either	Save plain text, not rich text. Check the real extension.

Replace the whole file with the lesson's complete example to find out whether an edit introduced the problem. Then make one small change at a time.

Unknown field, missing ID, or missing asset

Copy field names exactly: baseStats is not base_stats. An API 2 error may suggest a nearby valid spelling. Unknown custom fields can be preserved without changing gameplay, so silence is not proof that a guessed field works.

An ID is an internal name. Use Choose a Registry or find internal IDs rather than guessing from a display name.

An asset path such as assets/front.png is relative to the mod folder when used with mod.assets:path. Confirm the file exists, its capitalization matches, and its format fits Art Pipeline or Audio Authoring. A missing audio/image file may only fail when the game first tries to use it.

It loads but nothing changes

1. Save the edited file and restart the selected game.
2. Confirm the enabled mod ID and game. A mod can be enabled for one game and off for another.
3. Follow the exact checkpoint location/action. Registering content alone does not put an item in a shop or teach a Pokemon a move.
4. Temporarily turn off other mods affecting that same content and retry.
5. For a numerical change, inspect the value or use a controlled comparison. One random battle or encounter is not a reliable measurement.

Content definitions are combined at startup. A content-changing option can need a restart even though its checkbox changed immediately. See Lifecycle.

Read log output

Load errors are available in the manager. Ordinary mod.log:info messages are printed to the process output and stored in an in-memory history; this engine logger does not create a general desktop log.txt.

For a source checkout, open a terminal in the engine root and start the game there. On a system with love on its PATH:

love .

On macOS with LÖVE installed in Applications but no love command:

/Applications/love.app/Contents/MacOS/love .

Keep that terminal open while triggering the action. A log line starts with [info], [warn], or [error]. For example, the ID-listing mod below prints [info] [find_ids] TACKLE: TACKLE. The bracketed mod ID identifies the owner. Do not expect an info log line to appear as in-game dialogue.

Optional developer console

For a Red source run, enable developer mode. Press the backtick key in-game to open the console, type an expression, and press Enter. Press backtick again to close it. This is a debugging tool, not a required part of the first mod.

Console input — not a main.lua file:

data.pokemon.GROWLITHE.baseStats.speed

The displayed number is the loaded base Speed field, not a party Pokemon's calculated battle stat. For the most recent logger message, enter:

require("src.core.Logger").history[#require("src.core.Logger").history]

The console prints the returned value. The history contains up to 200 recent messages and starts fresh with the process. Console trace map.* traces map events while active; it is different from a permanent log file.

Find internal IDs

For source-checkout authors: make a temporary mod named find_ids using the manifest pattern in Getting Started. Use "id": "find_ids", "name": "Find IDs", and "games": ["red"]. Replace its entire main.lua with:

return function(mod)
  for id, record in mod.content.moves:each() do
    mod.log:info("%s: %s", id, record.name or "(no display name)")
  end
end

Launch Red from a terminal and read the printed IDs. :each() visits the collection; it is not a command you type on its own in a shell. Turn this mod off after inspecting the list. To inspect a different registry, change moves to that registry and choose a field its records actually contain. Do not package bulk imported data dumps as a mod.

The ROM will not import

Use a supported US game file matching the selected game. The importer checks the file's hash, a calculated summary used to recognize an accepted release. A renamed file is still the same data; renaming does not repair a mismatched dump or make a ROM hack supported.

The current source's accepted games/revisions are listed in GameVersion.lua. Red/Blue/Yellow are 1 MiB; Gold/Silver/Crystal are 2 MiB. Your installed release's error is the guide to what it accepts. Do not delete all saved files to troubleshoot an import; follow the relevant import/re-import control.

A command cannot find tools or an interpreter

• tools/modkit.py missing: you may be in the wiki or mod directory. Open the engine root containing tools/, or follow the manual packaged-app route.
• python3 or luajit not found: finish Developer Setup.
• Imported dataset missing: import the selected game first. A fixture check skips some real-ID checks and is not an equivalent replacement.
• A command shows its usage: replace placeholders such as /path/to/wiki with real paths. Quote paths containing spaces. Do not type square-bracket optional-argument notation literally.

Saves, link play, and recovery

Use Save Editor for selecting and recovering the correct save, and Save Model for removed content. Test new mods in a separate save slot and keep your own backup before a persistence lesson.

Link play is launched from the launcher, using a vanilla cart or a sealed custom cart. Mods may run inside that sealed cart; an arbitrary enabled mod set is not the link workflow. See Link Play and Link Compatibility for the current controls and sealed-cart requirements.

Save recovery

To undo an editor save, first keep the editor open and record the full save path shown in its title bar. Then close the editor and game, and open that directory in the file manager. Copy the current save to a temporary name such as slot1.lua.before-restore, keep it, and copy the timestamped backup beside it (for example, slot1.lua.bak-20260909-143000) back to the original save filename. Reopen the same launcher slot, or use Open... in the standalone editor, and confirm the restored value. Keep the backup and temporary copy until that check succeeds. If the path or backup name is unclear, stop before replacing a file and use Save Editor for the full procedure.

Technical sources: src/core/Logger.lua, src/dev/Console.lua, src/mods/ManagerState.lua, src/mods/Loader.lua, tools/modkit.py.