Hytale Server Mods Guide: Install, Verify and Troubleshoot Mods

How Hytale server mods work

The official Hytale Server Manual lists mods/ as the folder for installed mods, and its tips section says to download mods (.zip or .jar) from sources like CurseForge and drop them into mods/. The server reads that folder when it starts. There is no install command and no registry to edit.

CurseForge's own Hytale support article describes two broad kinds of content, and the difference explains the two file types. Treat this as the CurseForge description rather than a rule from the server manual:

The mods folder is part of the server's top-level layout, next to universe/ (world and player data), logs/, and the config files config.json, permissions.json, whitelist.json and bans.json. The server also has a launch flag, --accept-early-plugins, which the manual describes as acknowledging that loading early plugins is unsupported and may cause stability issues. You do not need it for ordinary mods. If a mod's page tells you to use it, understand that you are opting out of support for stability problems.

Where to find Hytale server mods

The official manual names CurseForge as an example source, and hosting documentation consistently points there too, so it is the sensible default. A few habits make downloads safer and save you debugging time:

• Open the mod's page and read the description before you download. Authors list the Hytale version they tested, required dependencies and whether the mod is server-side, client-side or both.
• Look at the file's own version information. A mod that has not been updated since several game updates ago may not work on the current build.
• Check the Relations tab on the CurseForge page for dependencies marked Required or Optional. A missing required dependency is one of the most common causes of a silent failure.
• Prefer mods with a visible author history, recent updates and real discussion over brand-new uploads with no feedback.

Avoid files sent to you directly (a link in a direct message, a file from a stranger in a chat). A plugin is not just data. See the security section below.

Install a mod on your ChicagoServers server

This uses the Files tab, which every game on the panel has. If you prefer a desktop client, the blue SFTP bar near the top of the server page gives you the host, port and username (the password is your panel password), and the steps are the same once you are connected.

1. Make a backup first

   Open the Backups tab, choose World and settings under Back up now, add a note such as "before adding mods", and click Back up now. Mods can change what the server writes into the world, so a restore point is cheap insurance. See the backups and world transfer guide for the details.

2. Stop the server

   At the top of the server page, click Stop. Stop saves the world and shuts the game down properly. Do not drop files into a running server's folders.

3. Upload the file into mods

   Open the Files tab, go to the mods folder, click Upload (or drag the file onto the page) and add the .zip or .jar exactly as you downloaded it. Do not use Extract here on a mod: the manual describes the .zip or .jar files themselves going in the folder. The file must sit directly in mods/, not inside a subfolder.

4. Start the server

   Click Start at the top of the page and open the Console tab to watch the startup output.

5. Confirm it loaded

   See the next section. If the mod has a command or a setting, test that too.

If your server page shows a Startup or Configs tab, you can look there, but the panel does not document mod options for Hytale, so ask 24/7 support if you are unsure. If you are unsure how mods or launch flags are handled on your plan, ask 24/7 support rather than guessing.

Verify that a mod actually loaded

The official manual does not document the wording of mod-load messages, and the wording differs from mod to mod, so there is no single line to search for. What works reliably:

1. Watch the Console tab during startup and look for the mod's name. A mod that loads usually announces itself or at least appears in startup output without an error next to it.
2. Read the newest file in the logs/ folder (the manual lists it as the server log files) on the Files tab and search for the mod's name and for the words error, exception, failed and missing.
3. Use the mod. If it adds a command, run it from the Console or in game. If it adds content, check that the content appears.
4. Check that the server is still healthy. The Troubleshoot tab lists crashes and failed starts from the last 14 days with a likely cause, which helps when a mod makes the server restart repeatedly.

Client and server compatibility

There are two separate compatibility questions, and people often mix them up.

Game version. The official manual is clear that the client and the server must be running the exact same protocol version. If Hytale updates on the player's side before your server has updated (or the other way round), players cannot join regardless of mods. The manual also mentions that a tolerance of plus or minus two protocol versions is planned, but that is a future feature, so do not rely on it.

Mod placement. Sources disagree on whether players need to install server mods, and the honest answer is that it depends on the mod. One hosting guide says players on a modded server do not download mod files because the server streams the content when they join. CurseForge's support article says players should receive content automatically when joining a server. Another says that mods which are client-side or require both sides must also be installed on each player's game. The reliable approach is to read the mod's own page and look for words such as server-side, client-side or both.

If players do need a mod locally, community guides report that the game's client mods folder is UserData/Mods inside the Hytale data folder. On Windows, that is reported to be %AppData%\Hytale\UserData\Mods, and you can reach it by pasting that path into the Windows address bar. Single-player worlds are a different case: mods are reported to be off by default and must be enabled per world in the world settings.

Remove a broken mod or fix a server that will not start

If the server will not start, or starts and then stops, the most recent change is the first suspect.

1. Stop the server

   If it is stuck, use Stop first. A Kill button appears if it will not stop; it ends the process without saving, so use it only as a last resort.

2. Read the end of the log

   Open the Console tab and the newest file in logs/. A mod named next to an error, a missing-dependency message or a version complaint tells you where to look.

3. Remove the newest mod

   On the Files tab, delete (or move out of mods/) the file you added most recently, then start the server.

4. Check for duplicates and dependencies

   Two copies of the same mod with different version numbers cause trouble. Keep one. If the mod needs a library or companion mod, install it into the same folder.

5. Isolate conflicts

   Take every mod out, confirm the server starts clean, then add them back one at a time, starting the server after each one. The last one added before the problem returns is the likely cause.

6. Restore if the world is affected

   If the world will not load, or content from a removed mod has left gaps, open Backups and restore the backup you took before adding mods, leaving Save the current files as a restore point first ticked.

Removing a mod that added content to your world can leave data behind that nothing now understands. The per-world config.json (under universe/worlds/) includes a RequiredPlugins field, and a community guide reports that a world will not load when a plugin listed there is missing. If a world refuses to load after you removed a mod, look at that field, but stop the server before editing and keep a backup, because Hytale rewrites its config files while it runs and the manual warns that manual changes made on a running server are likely to be overwritten.

The Troubleshoot tab on the panel suggests the same order of operations for any game: read the last lines on Console, undo the last mod or plugin you added, and restore a backup from before the problem if needed.

Security and trust

A .jar plugin is Java code that runs inside your Hytale server process. It can do whatever the server process can do: read and write files in the server's folder, open network connections, run commands. The manual itself flags unsupported early plugins as a stability risk. That is not a reason to avoid mods, but it is a reason to be selective.

• Download from the mod's page on CurseForge, not from a re-upload on a random site, and not from a link in a direct message.
• Prefer mods with a named author, a changelog and recent updates. Be cautious with mods that ask for unusual access or tell you to run extra commands or disable protections.
• Do not enable --accept-early-plugins unless a mod you trust explicitly requires it.
• Never store credentials in a mod's config unless you understand what the mod does with them.
• Keep operator rights tight. Anyone who can place a file in mods/ (through the Files tab or SFTP) can run code on the server, so give panel file access only to people you trust. The permissions guide covers sub-user access.

ChicagoServers includes DDoS protection on every server, but that protects the network, not the contents of a plugin. A hostile or buggy plugin is a different problem that only your own choices can prevent.

Early Access breakage and updates

Expect mods to break after significant game updates while Hytale is in Early Access. This is normal and temporary. Mod authors need time to rebuild against a new server version, and community guides repeatedly advise checking a mod's supported version before updating.

• Before you apply a Hytale update, take a backup, then check each mod's page for its supported version.
• If a key mod has not been updated yet, you can hold the server on its current build rather than updating. The manual documents update controls such as the /update check command and the HYTALE_DISABLE_UPDATES environment variable, but how updates are handled on a ChicagoServers Hytale server is something to confirm with support.
• After the update, start the server with the same one-at-a-time discipline: if it fails, remove the newest or least up-to-date mod first.
• Update mods and their dependencies together, and replace old files instead of leaving two versions in mods/.

If something goes wrong with performance after you add several mods at once, the performance guide shows how to separate a mod problem from a view distance or hardware problem.

Running this on ChicagoServers

On a ChicagoServers Hytale server you get the Files tab and SFTP for uploading mods, the Console tab for checking startup, Backups for a restore point, and Troubleshoot for crash and failed-start history. If a mod will not behave, 24/7 support can help you read the logs.

Frequently asked questions