How to Install Mods on a Hytale Server

Use this order every time: add, update and remove

The safest way to manage mods is to treat every change as a world compatibility change, not just a file upload. Hytale keeps world and player saves in universe/, reads mod files at startup, and writes config changes back to disk while it runs. Hytale is also in Early Access, with updates arriving often, so the mod set you install today will need checking again after every big patch. That means careless live edits, partial uploads or version mismatches can leave you with a server that boots badly or a world that cannot open at all.

That order matters more on a live server than on a private test world. If friends are already building, storing items and travelling far from spawn, every mod change potentially touches save data, loaded chunks, inventories, and plugin-specific storage.

The three kinds of Hytale mods and where each goes

First make sure you know which kind of file you are installing. The folder is different for early plugins, and the loading rules are different too.

Players do not install server mods to join. Hytale asset packs and mods can exist entirely on the server side, so your job is to place them in the right server folder and confirm they loaded correctly.

server/
├─ logs/
├─ mods/
│  ├─ plugin-example.jar
│  ├─ pack-example.zip
│  └─ plugin-example/
│     └─ config.json
├─ universe/
│  └─ worlds/
├─ config.json
├─ permissions.json
└─ whitelist.json

The main mistakes here are simple ones: uploading into the wrong folder, putting a mod inside an extra subfolder, or unzipping an asset pack that should have stayed as a single archive. Hytale scans the expected locations on startup; if the file is nested too deeply, there is nothing to load.

Before you install: check the exact build, the manifest and the dependency chain

Do this before you upload anything. Hytale requires the client and server to run the exact same protocol version, and plugins also declare what server versions they support in their manifest.json using ServerVersion. Chapter 1 / Update 7 changed both the protocol and much of the plugin API, which is why many Update 6 plugins need rebuilt versions before they will load cleanly on current servers.

Start with /version so you know the server’s exact build, not just a rough update name. Then check the mod’s manifest details:

• ServerVersion: the compatible server version range. If it does not include your build, expect a startup failure or disabled plugin.
• Dependencies: required plugins by identifier and version range. If one is missing or out of range, the plugin fails to load.
• OptionalDependencies: these are not required, but if present and on the wrong version they can still break the load.
• IncludesAssetPack: a plugin .jar can also carry an asset pack, so one file may affect both logic and visible content.

The reason this check matters is that compatibility failures happen early, on the server’s main startup path. You are not dealing with a harmless warning; you are asking the server to build a load order, resolve plugin identifiers, and initialise code against a specific API. If the API changed underneath it, the server often has to stop rather than continue in a half-loaded state.

One more trap: mods installed through the in-game Mod Browser go into your own Hytale installation, not onto the server. That is useful for personal play, but it does not populate the server’s mods/ folder. For a rented server, download the same mod files in the same versions and upload them to the server manually.

The safe install order, step by step

If you only keep one routine, keep this one. It reduces file corruption, avoids partial loads, and makes it obvious which mod caused trouble.

1. Back up first. Take a full backup before each mod change, not just before “big” ones. Even a small plugin can alter world data, inventories or generated chunks.
2. Stop the server. Do not upload or edit active mod files while the server is running. The server reads mods at startup, and live file changes can leave old code in memory with new files on disk.
3. Upload the file directly into mods/. Do not put it in a subfolder. For asset packs, upload the .zip as-is unless the pack is meant to be a folder. For large files, or if your panel’s browser upload is limited, use SFTP.
4. Start the server and read the console. Do not assume “started” means “loaded correctly”. Look for missing dependencies, duplicate plugin messages, compatibility warnings and world-load failures.
5. Confirm from inside the server. Use /plugin list for plugins and /packs list for asset packs so you are checking the actual loaded state, not just the file list.
6. Join and test. Log in, check commands, assets, world generation and anything the mod touches. Only after that should you add the next mod.

/version
/plugin list
/packs list

Install one mod at a time on a server with active players. That is not busywork; it isolates cause and effect. If you upload three files and then the world will not boot, you have created a dependency puzzle. If you upload one, the answer is usually in the next console output.

Also keep the file handling clean. A half-finished browser upload or a badly nested archive wastes time because the server cannot load what it cannot see. If a pack is large, SFTP is usually the safer route because it avoids browser upload limits and interrupted panel sessions.

If mods raise server load: tune first or move to a stronger plan?

Mods can increase server load even when they install properly. The key is to identify which resource is under pressure. On Hytale, CPU load rises mainly with high player or entity counts, while RAM rises with a large loaded world area, especially when players explore independently. View distance is the main RAM driver, and Hypixel recommends limiting the maximum view distance to 12 chunks (384 blocks).

How do you tell a tuning change helped? Look for fewer lag complaints during the same kind of activity, shorter or less frequent pauses when players travel apart, and cleaner console behaviour after long sessions. If lowering view distance stabilises the server, that is a RAM win. If trimming entity-heavy content helps but long-range exploring still hurts, the world area being loaded is still your bigger problem.

If you are unsure how to judge the balance between memory and processor load, our guide to how much RAM and CPU a game server needs will help you read those symptoms properly before you blame the wrong mod.

Configuring a mod without losing your changes

Many plugins create their own settings folder inside mods/ the first time they load. That is where you usually find per-plugin config files. Hytale also writes its own files such as config.json, permissions.json and similar during normal server activity, so edit only while the server is stopped.

This matters because the server does not treat disk files as read-only after startup. If an in-game action changes a setting or plugin state, the server can write its current version back out and overwrite your manual edits. When people say a config “did not save”, the usual cause is that they edited the file live and the running server wrote over it.

• Start the server once so the mod can generate its default config.
• Stop the server before editing anything under mods/ or the main server folder.
• Change one setting group at a time, then restart and test.
• Keep a copy of the old config before major edits, especially if a plugin controls world generation or player permissions.

Most servers never need to touch Mods, ModLoadOrder or DefaultModsEnabled in the main config.json. If a plugin works with the normal mods/ load process, leave those alone unless you have a very specific reason to change load behaviour.

Updating mods safely after a Hytale update

Hytale updates are the point where most modded servers get into trouble. The client and server must be on exactly the same protocol version, so once players update, the server has to follow or nobody on the new version can connect. Bigger updates can also change the world format: with Chapter 1 (Update 7, 12 October 2026), worlds upgraded on first load and could no longer be opened by an older server. That is why you do not push the server forward until every plugin your world needs has a compatible build ready.

The safest order is simple: check mod compatibility first, back up second, update the server third, then replace each old mod file with its matching new build. Do not leave the old .jar in place next to the new one or the server can try to load the same plugin twice.

If a plugin your world depends on has no compatible build yet, you have a real choice to make: hold the server on the old version for a few days (players who have already updated cannot join until you move), or update and run without that plugin, which only works if the world does not list it as required. Neither is free, so look at the mod’s page before you decide, not after.

/update check
/update status
/update apply --confirm

{
  "Update": {
    "RunBackupBeforeUpdate": true,
    "AutoApplyMode": "Disabled"
  }
}

RunBackupBeforeUpdate is worth leaving enabled because it gives you a rollback point before binaries change. AutoApplyMode needs thought: Disabled is the cautious option for modded servers because you can verify plugin support before applying anything. Automatic modes are convenient, but convenience is not the same as compatibility, especially in Early Access where updates are frequent.

Hytale’s updater keeps config, saves and mods while selectively replacing server binaries and the main assets. That protects your files, but it does not magically make an older plugin API-compatible. Use /update check and /update status to see what is waiting, and run /update apply --confirm only once you know the mod set is ready.

If your panel starts the server with regular backups already enabled, keep that behaviour on. The default wrapper scripts back up every 30 minutes, and the updater also keeps previous files in updater/backup/, which is useful if you need to unwind a bad patch or mod pairing.

Removing mods safely from an existing world

Removing a mod is riskier than adding one because the world may already depend on it. Hytale stores world and player save data under universe/, and each world has its own config file inside universe/worlds/<name>/. That file includes a RequiredPlugins entry.

{
  "RequiredPlugins": {}
}

Failed to load world! Missing plugin

If a removed plugin is recorded there, the world fails to load with that error. Mechanically, this is Hytale protecting world integrity: it sees a world that was saved with a required plugin present and refuses to open it without that requirement met.

Content mods carry another risk. If the mod added blocks, items or other world content, removing it can leave gaps where those assets used to exist. That is not just a visual nuisance; it can alter builds, inventories and generated areas permanently.

1. Take a fresh backup.
2. Stop the server.
3. Remove the plugin or pack file.
4. Start the server and watch for a missing plugin or world load error.
5. If the world fails, put the mod back immediately or restore the backup from before the mod was introduced.

In practice, the clean rollback route is often the right one. If your goal is to “try removing it and see”, do that only on a copy of the world or with a full backup ready to restore.

Early plugins: powerful, separate and deliberately unsupported

Early plugins are not normal server mods. They go into earlyplugins/, not mods/, and they work by rewriting server code while the server loads. That is why Hytale requires an explicit acknowledgement flag: --accept-early-plugins.

Without the flag, startup pauses at a warning instead of continuing. The server does not create the earlyplugins/ folder for you either, so you must add it yourself in the directory the server runs from.

Why the caution? Because an early plugin changes boot-time server behaviour at a lower level than an ordinary plugin. If it is wrong for your build, it can break startup itself rather than just disabling one feature. The upside is deep control; the downside is higher stability risk and more difficult diagnosis when something goes wrong.

Use early plugins only when you know exactly why a normal plugin cannot do the job. For ordinary commands, permissions, server rules and most community features, stick to standard plugins in mods/.

Troubleshooting after a mod change

If the server will not start after adding or updating a mod, read the load order clues first instead of guessing. Most failures come from version mismatch, duplicate files, missing dependencies, wrong folders or a removed required plugin.

[HytaleServer] Failed to boot HytaleServer! java.lang.IllegalArgumentException: Tried to load duplicate plugin

That duplicate error is the classic update mistake: uploading a new plugin build without deleting the old one first. The server identifies plugins by their manifest identifier, not by the filename alone, so renaming the old file does not solve it if both copies are still present.

Keep a simple mod list so rollback is easy

A plain text note or spreadsheet is enough. Record the mod name, version, source, date added, and any dependencies it needs. If you later update Hytale, have to restore a backup, or need to rebuild the server after a failed change, that list saves a lot of guesswork.

This also helps when you install mods on a Hytale server for a small community and someone asks, “What changed since last week?” You can answer quickly, revert the right file, and avoid removing three unrelated plugins just to fix one bad update.

Hytale server FAQ

Do players need to install mods to join a modded Hytale server?

No. Hytale asset packs and mods can exist entirely on the server side, so the server or world host installs them and players join normally. That is why getting the server folders and versions right matters more than telling players to fetch matching files.

Where is the mods folder on a Hytale server?

Inside the main server folder there is a mods/ directory specifically for installed mods. Standard plugin .jar files and asset pack files go there, while early plugins belong in a separate earlyplugins/ folder in the server’s run directory.

Why won’t my Hytale server start after adding a mod?

The usual causes are wrong server version support, a missing dependency, a duplicate plugin left over during an update, or the file being placed in the wrong folder. Read the startup console first, then check /version, the mod manifest, and the exact file location before changing anything else.

Can I remove a mod from an existing Hytale world?

Sometimes, but it is not automatically safe. Worlds can record required plugins, and content mods can leave missing blocks or items behind, so always back up first and expect to restore if the world refuses to load or important content disappears.

Do Hytale mods work after a game update?

Not always. Because clients and servers must match the exact protocol version, the server has to update, but plugins also need builds that support the new API and server version range. Check mod compatibility before applying the server update, especially after larger updates such as Chapter 1 / Update 7.

More Hytale server help

Compare hosts, or check what your modded server needs in RAM and CPU.