Jotunn for Valheim: what it does and why it kicks players

Jotunn is not a mod you install for its own sake. It is a library - "the Valheim Library" - that other mods are built on, and it ends up on most modded servers because a content mod listed it as a dependency. It does three things a server owner notices: it registers the new items, pieces and creatures those mods add, it compares mod versions between server and client when someone connects and disconnects them if they do not match, and it pushes admin-only config values from the server to every client. When a player is kicked from a modded server with a window listing mods and versions, Jotunn is very often the thing doing the kicking - and it is doing it on purpose. This post explains what is happening, how to read it, and how to keep Jotunn itself from becoming the mismatch.

How BepInEx loads mods in the first place is covered in Valheim server mods with BepInEx. This post picks up from there.

What Jotunn does for mods#

Valheim has no official modding API. Without a library, every content mod would have to work out on its own how to inject a new item into the game's object database at the right moment, how to make a recipe show up at the right crafting station, how to add translations, and how to register network messages. Jotunn does that work once, and mods call it.

It is organised into managers, each responsible for one kind of thing:

Most of this is invisible to a server owner, with one useful exception: Jotunn introduced "mock" references, where a mod refers to a vanilla asset by a placeholder name prefixed JVLmock_ that is swapped for the real object at runtime. If a mod's assets fail to resolve after a game update, you may see that prefix in error lines in the log, and it points at a mod that needs updating rather than at your install.

Jotunn is published on Thunderstore as ValheimModding-Jotunn, with documentation at valheim-modding.github.io/Jotunn. It depends on BepInExPack Valheim and on HookGenPatcher (ValheimModding-HookGenPatcher), which generates MMHOOK assemblies for the game on first start. A mod manager installs both automatically. By hand, Jotunn's .dll goes in BepInEx/plugins and HookGenPatcher goes in BepInEx/patchers - putting HookGenPatcher in the wrong folder produces errors that look as if Jotunn itself is broken.

Where Jotunn has to be installed#

Jotunn has to be on every machine that runs a mod depending on it. In practice that means the server and every client, because content mods - the main users of Jotunn - are themselves needed on both sides.

A server-side-only mod that happens to use Jotunn needs Jotunn on the server only. A client-only mod that uses it, such as some interface mods, needs it only on the clients. The dependency follows the mod. The common surprise is a group that thinks it is running "only server mods" until someone adds one content mod and Jotunn arrives with it, at which point the server is no longer joinable without the same mod on every client.

That is also why Jotunn mods lock out Xbox and Game Pass players: they cannot install anything, and Jotunn's check will refuse them if a mod declares that everyone must have it. Valheim crossplay and Xbox players covers what a mixed group can and cannot run.

The version check, and why it kicks players#

When a client connects to a server, Jotunn on each side builds a list of loaded mods that have declared a network compatibility level, with their versions, and the two lists are compared. If they disagree in a way a mod has said matters, the client is disconnected and shown a window listing the problems.

Each mod declares its requirement in code with an attribute. Two parts matter: who must have the mod, and how strictly versions have to match.

So a content mod that declares EveryoneMustHaveMod with Minor strictness lets a player on 1.4.2 join a server on 1.4.3, but refuses 1.5.0. A mod that declares Patch strictness refuses any difference. A mod that declares nothing is not part of Jotunn's comparison at all - which does not mean it is safe to mismatch, only that Jotunn will not tell you.

The window the player sees lists each offending mod and what was wrong: missing on the client, missing on the server, or present on both at incompatible versions, with both versions shown. That window is the most useful thing in the whole process, because it names the mod. Ask the player for a screenshot rather than a description.

The fix is always the same: make the lists agree. Do not try to loosen the check. The authors declared strictness because a mismatched version will break items, recipes or the world in ways that are much worse than a refused connection. The step-by-step for reading the message and matching sets is in kicked for mod version mismatch.

Jotunn itself as the mismatch#

The awkward case is when the content mods all match but Jotunn does not. A player who updated everything in their mod manager now has a newer Jotunn than the server. Whether that alone kicks them depends on the Jotunn versions involved, and it has differed between releases - but even when it does not kick them, a content mod built against newer Jotunn behaviour can misbehave against an older one on the other side.

The safe rule is simple: treat Jotunn as part of the mod list and keep it at the same version on server and clients. When a group shares a profile through a mod manager, Jotunn is in the profile like any other package, and r2modman for Valheim groups shows how to keep that profile pinned.

To see what each side is actually running, read the BepInEx log. Every plugin is listed at start-up with its version:

# On the server, from the server root$ grep -o 'Loading \[[^]]*\]' BepInEx/LogOutput.logLoading [Jotunn 2.x.x]Loading [SomeContentMod 1.4.3]

On a client the same file is in the profile's BepInEx folder, after one modded start. Compare the two lists line by line.

Config sync and admin-only settings#

Jotunn gives mods a way to make some config values server-authoritative. A mod marks a setting as admin-only, and Jotunn's SynchronizationManager then does three things:

• When a client connects, it sends the server's values for those settings to the client, which uses them for the session instead of its own.
• While connected, a client that is not an admin cannot change them; the values are shown locked in the in-game config editor.
• A client that is an admin can change them in game, and the change is sent to the server, saved there, and pushed to every other connected player.

Admin status comes from the server's adminlist.txt, the same file vanilla uses for kick and ban - the three list files explains the ID formats. If an admin cannot change a synced setting in game, the first thing to check is whether their ID is in that file in the form the server expects.

The in-game editor most people use is BepInEx Configuration Manager, opened with F1 by default. It is a client-side mod, not part of Jotunn, but Jotunn's sync hooks into it. Without it, admins can still edit the server's file in BepInEx/config and restart.

Two consequences worth knowing:

1. Editing a synced value in a client's config file does nothing on a server. It is overwritten on connect. Players sometimes report a mod "ignoring" their change; this is why.
2. The server's config file is the record. Back it up with the world, and when you move the server, take BepInEx/config with it, or every synced setting returns to the mod's defaults.

Not every mod uses Jotunn's sync. Some carry their own synchronisation, most often the ServerSync library, which behaves similarly but separately, usually with a Lock Configuration setting in the mod's own config. A mod's page or its config comments say which it uses.

Keeping Jotunn current#

Jotunn is maintained by the Valheim modding community and is usually among the first packages updated after a game patch, because so many mods depend on it. The order on patch day:

1. Do not update the server the moment the patch is out. Stop it, back up the world and the whole BepInEx folder.
2. Wait for BepInExPack Valheim (if the patch changed Unity), then HookGenPatcher and Jotunn, then the content mods. Content mods often pin a minimum Jotunn version in their dependencies, so they cannot be updated first anyway.
3. Update the server and its mods together, start it, read the log for exceptions and for the hook generation finishing.
4. Share the new mod profile with the group only after the server is confirmed working.

Jotunn tries to stay backward compatible within a major version, so a mod written for an older Jotunn usually still works with a newer one. A major version change can break that, and authors note it in their changelogs. What to do when a mod update breaks is the general procedure when the order above does not save you.

On RE:NODE, backup slots are included on every Valheim plan, so take one on demand before you touch anything - with a working Jotunn and mod set in it - and restoring is one button if the update goes wrong. A backup can also be locked so scheduled backups do not rotate it out while you are still testing.

Troubleshooting Jotunn#

`Could not load [SomeMod] because it requires [com.jotunn.jotunn]`. Jotunn is missing or failed to load. Install it, and check that HookGenPatcher is in patchers, not plugins.

Jotunn loads but throws on start after a game patch. Jotunn has not been updated for this game version yet, or HookGenPatcher's generated assemblies are stale. Update both; if that is not possible yet, run without the dependent mods until it is.

A player gets a window listing mods on connect. That is the version check. Read the names and versions in the window and make their profile match the server.

Admin changes to a synced setting do not stick. The player is not recognised as an admin by the server, or the setting is not one the mod marks as admin-only. Check adminlist.txt first.

Start-up takes several minutes. The first start after installing or updating HookGenPatcher, or after a game patch, regenerates hook assemblies. Later starts are faster. If every start is slow, count the mods rather than blaming Jotunn.

FAQ#

Do players need Jotunn installed?

If any mod they need depends on it, yes. A mod manager installs it automatically as a dependency. Players only need it separately if a mod on the server declares that everyone must have the mod and the mod uses Jotunn.

Can I turn off Jotunn's version check?

Not from a config file, and you should not want to. Each mod declares its own requirement in code. The check exists to stop items, recipes and world objects disagreeing between machines.

Is Jotunn the same as JotunnLib?

JotunnLib was the earlier name. Current packages are published as Jotunn by ValheimModding, and old mods that mention JotunnLib generally mean the same library.

Does Jotunn cost server performance?

Very little once running. Its main cost is start-up time from HookGenPatcher's generation and from registering content, which matters more as the mod list grows.

Why does Jotunn need HookGenPatcher?

Jotunn and many mods built on it use hook assemblies, generated from the game's code, to attach to game methods. HookGenPatcher generates those assemblies on start and regenerates them when the game updates.