Reference
Troubleshooting
Fixes for the most common modding problems, from a missing Mods button to lost data, errors and broken downloads.
Find your problem below. If it is not here, your mod's Log (Mods, your mod, Log) usually says what went wrong. Still stuck? Ask in the Eaglercraft Discord.
I cannot find the Mods button
Mods only exist in Eaglercraft 26.2 and 26.3. The 1.8 and 1.12 clients do not have them. In 26.2 and 26.3, Mods is on the title screen, next to Options..., where Quit Game is in the normal game. It is not in the pause menu.
My new block, item or mob is missing
The game adds blocks, items and mobs when it starts. After you install a mod, turn one on or add something new to register, reload the page.
Still missing? Check the mod's Log for a message about it, and make sure you are in your own world. Servers and other people's LAN worlds do not have mod blocks, items or mobs. See Where it works.
My block shows as a purple and black checkerboard
The game could not find its texture. Check that the path in texture matches the file in your zip exactly, including the folder and the .png at the end. Paths are case sensitive.
The file picker does not open
Browsers only open a file picker right after a click or a key press. Call files.open from a button, a keybind or a chat command, not from a timer or tick. When it cannot open, files.open gives back false and a message. See Files from your computer.
My mod stopped, or says Error
Click Log and read the last lines. The reason is also in the mod's details.
| What it says | What happened |
|---|---|
| too many errors | your code hit 30 errors in a minute, usually a broken HUD or tick function that fails every frame |
| script took too long | your code ran past its budget, usually an endless loop |
| Failed to load | the error happened while main.lua was loading, so the mod never started |
| requires the mod ... | a mod it depends on is missing, turned off or broken |
Fix the code, then click Save & reload in the editor or Reload in the Mods menu.
My mod says Not loaded
It is turned on but not running. This usually means a mod it depends on was turned off, deleted or updated. Turn that mod back on, or install it, then click Reload on yours.
Settings is greyed out
The Settings page only opens while the mod is running and has at least one setting. It is greyed out when the mod is turned off or stopped by an error.
My setting reads as a function
The setting's key is the same as a settings function, like color or text. settings.color is the function that makes color settings, so a setting named color can only be read with settings.get("color"). Give it another name, like textColor. See Settings and storage.
My saved data is gone
- You replaced
storage.storage = {}makes a new table that is never saved. Change its fields instead:storage.kills = 0. - The tab closed before it saved. Storage saves every 15 seconds and when your mod unloads, not when the tab closes. Call
mod.save()after anything important. - Something could not be saved. A function or other game object in
storagestops the whole save. The Log says "could not save storage". - The browser's data was cleared. Mods and their data live in your browser. Clearing this site's data deletes them.
My code changes are gone
Close and Escape in the editor throw away anything you did not save, without asking. Click Save & reload first. Updating a mod also replaces your edits with the new version, so export your copy before you update.
My mod does nothing when I am already in a world
world_join only fires when you join a world. If your mod loads while you are already in one, it never sees that event. Check player.exists() when your mod starts. See How mods run.
The § in my text disappears
The game's editor and paste box remove the § character. Write "\u{00A7}" in its place: "\u{00A7}aGreen" is green text.
My colors are see-through or solid when they should not be
A number color with 00 alpha, like 0x00FF0000, is drawn solid. To make something see-through, use a hex string: "#80FF0000" is half see-through red. Short colors like "#F00" do not work either, so always write all six or eight digits.
Everything on the screen moved
A ctx:translate, scale or rotate without a matching push and pop moves everything drawn after it, including the game's menus. Wrap them in ctx:push() and ctx:pop().
My tooltip does not show
ctx:tooltip only shows on screens, like your own ui.screen. It does not show on the HUD.
My buttons on a game screen disappear or show up twice
Add buttons inside screen_init. It fires again whenever the screen is rebuilt (for example when the window is resized), and the buttons are cleared each time, so they come back on their own. Adding them anywhere that runs every frame adds a new button every frame.
My command does not work
- Mod commands only work from the chat box, not from
chat.sendorchat.command. - Two mods cannot have the same command. The second one gets an error. Check its Log.
Download failed
Downloading a mod from a link needs the website to allow cross-origin requests (CORS), and many file hosts do not. Download the file yourself and drop it on the game instead. The same goes for web requests in your own mod: see What the server has to allow.
A function says it needs a permission
Add the permission to your mod: network for http.get, http.post and http.request, clipboard for clipboard.get, microphone for mic.start and webrtc for rtc.connect. See Packaging.
The microphone does not start
mic.start gives back false and the reason, and its callback gets the reason too. The usual ones:
- "right after a click or key press": call
mic.startfrom a button, a keybind'sonPressor a chat command, not when your mod loads or from a timer. - "blocked": the player said no. They can allow it again from the lock icon next to the address in their browser.
- "this page does not let the game use the microphone": the page that shows the game in a frame does not allow the microphone. It needs
allow="microphone"on its<iframe>. - "needs an https page": browsers only give the microphone to https pages (and to
localhost).
Players cannot hear each other
- Check
onState. If it never saysconnected, the offer or the answer did not arrive, or the players' networks need a TURN server iniceServers. - The caller needs
peer:accept(answer)after the other player answered. - Use
mic = trueinrtc.connect, callmic.start, and make sure the microphone is not muted. - Check the player's Voice/Speech and Master volume. Voices use the
voicecategory unless you chose another.
The share code does not work
- The paste box holds 200,000 characters, and longer codes are cut off. Save the code in a
.txtfile and import that file, or share the zip. - "That share code is damaged" means part of it is missing or changed. Copy it again.
This mod needs a newer mod API
The mod was made for a newer version of Zeus than your game has. Play the newest version of Eaglercraft, or ask the mod's author for a version with "api": 1.
My WebAssembly mod will not load
| What it says | What to fix |
|---|---|
| A WebAssembly mod needs a metadata.json next to it | put the .wasm file and metadata.json in a zip |
| the limit is 8 MB | make the file smaller, for example with size optimizations |
| the module must export a function "zeus_init" | your SDK setup is missing its start function |
| ... is not supported | your language uses a WebAssembly feature Zeus does not have, like threads or GC |
| took too long (ran out of fuel) | your code ran past its budget, usually an endless loop |
| ran out of memory | your mod used more than 256 MB |
See WebAssembly mods for every limit.



