Hytale Server Whitelist and Access Control Guide (Update 6)

If you run a whitelisted Hytale server, Update 6 replaced the machinery under your feet without changing a single command your moderators type. The whitelist is no longer a file holding a list of names. It is a permission, and everything on your server that can hand out a permission can now hand out access. The one line version: copy whitelist.json off the box before you update, expect the server to rename it to whitelist.json.migrated, and afterwards verify access by having someone connect rather than by reading the whitelist listing, because the listing and the enforcement no longer describe the same set of players. We covered the announcement itself in our Update 6 Part 12 patch notes write-up. This guide is the other half of the job: what to actually do, and two behaviours documented in the official server API that appear in no patch note at all. Where This Information Comes From Two primary sources, and it is worth knowing which claim rests on which. The first is the official rolling pre-release patch notes page, whose "Pre-Release (Update 6 Part 12)" section is dated August 13, 2026. The second is the official Hytale Server API documentation, published as a stable Javadoc and a pre-release Javadoc. Almost everything genuinely new below comes from the second one. That includes the build number. Our Part 12 article said the patch notes name none and refused to infer one, which is still true of the notes. The pre-release documentation site self-reports its own version, and it reads Hytale Server API 0.6.0-pre.12 against 0.5.4 on the stable site. So, precisely: the patch notes still do not name the build, the API documentation does. What Actually Changed in Update 6? The patch note is four sentences: "The HytaleWhitelistProvider has been removed. The whitelist now runs on the hytale.server.join permission, and the whitelist commands grant and revoke it. If you have an existing whitelist.json it will migrate to whitelist.json.migrated." The API diff between the two documentation sites backs that up exactly, and it is worth being able to check. Comparing the published type list on 0.5.4 against 0.6.0-pre.12, the access control package loses one type and gains four. Gone in 0.6.0-pre.12: HytaleWhitelistProvider, plus the old ban classes InfiniteBan, TimedBan and BanParser. New in 0.6.0-pre.12: JoinPermissionProvider, BanProvider, BanStorageProvider and DiskBanStorageProvider. One of those deserves a flag. BanParser is not mentioned in the patch notes anywhere; its removal is visible only in the API diff. If you maintain a plugin that read ban files by hand, that is a compile break nobody told you about in prose. The change is a swap of mechanism, not of interface: access used to be decided by a provider that owned a list, and is now decided by JoinPermissionProvider asking the permission system a question. Every consequence below follows from that. Why Did My Hytale Whitelist Stop Working? Because the server no longer reads whitelist.json. On first start after the update it renames that file to whitelist.json.migrated and moves the entries into permission grants. The rename preserves your old data and stops anything else silently half-reading the old file. What it does not do is prove the migration worked: a renamed file tells you the step ran, not that every entry arrived. Before updating, copy whitelist.json off the box. Not a rename in place, an actual copy, alongside whatever backup routine you already run. Our anti-grief, rollback and backups guide covers making that habitual. After updating, confirm whitelist.json.migrated exists. If it does not, and you had a whitelist, stop and find out why before letting anyone connect. Then test with a human. Have a known whitelisted player who is not an operator actually connect. Operators are a bad test, for reasons the next section makes clear. If the server will not start at all, that is a different problem, most likely the Part 12 change where a failed core plugin halts startup instead of limping on. Our crash recovery and config guide is the place to start. The Whitelist Commands Did Not Change The most reassuring fact available, and it is checkable: all eight whitelist command classes exist in both 0.5.4 and 0.6.0-pre.12. Nothing was renamed, so your moderators need no retraining and your staff documentation no rewrite. The pre-release Javadoc describes the collection like this, verbatim: WhitelistCommand: "A command collection for whitelist-related commands." WhitelistAddCommand: "A command that adds a player to the whitelist." WhitelistRemoveCommand: "A command that removes a player from the whitelist." WhitelistEnableCommand: "A command that enables the whitelist." WhitelistDisableCommand: "A command that disables the whitelist." WhitelistListCommand: "A command that lists the whitelist." WhitelistStatusCommand: "A command that displays the whitelist status." WhitelistClearCommand: "A command that clears the whitelist." Two more sit beside them: BanCommand, "A command that bans a player," and UnbanCommand, "A command that unbans a player." One caution, which we apply to ourselves: the documentation names classes and describes what they do, but does not publish the literal command strings or argument order. The honest statement is that the server exposes add, remove, list, enable, disable, status and clear. Anyone printing exact syntax is reconstructing it, not quoting it. Verify against your own console, alongside our server console commands guide. What changed is only what happens underneath. Add now grants hytale.server.join. Remove revokes it. Clear revokes it from everyone who was granted it. Enable and disable flip whether the requirement is enforced at all. A general official Hytale screenshot. It does not depict the whitelist, a permission screen or any server console, because no official Hytale screenshot does. The Lockout Trap: Turning the Whitelist On Refuses Everyone Here is the part that is in the API documentation and in no patch note. The new JoinPermissionProvider class carries this description, quoted in full: "Refuses a player who does not hold HytalePermissions.SERVER_JOIN while the server requires it, which is what the whitelist of a server is. The permission belongs to no group, so a server that turns the requirement on refuses everyone until it grants it. An operator keeps their way in, because the admin group holds every permission." The permission belongs to no group by default. Not a default group, not a member group, nothing. So the moment you switch the requirement on, before granting anything, the documented behaviour is that every player is refused. Not an error, not a bug, not a broken update. That is the design. Operators keep their way in. The admin group holds every permission, which makes an operator the worst possible person to test a whitelist with. Enable the requirement, connect yourself, see it work and walk away, and you have verified nothing. You will hear about it from a support ticket. The sequence that avoids this is short enough for a sticky note: Grant join access to the players who should have it first. Turn the requirement on second. Test with a non-operator account third. The other order gives you a working server, an empty player list and no obvious cause. Rehearse it on a throwaway pre-release instance rather than on the live box; our pre-release testing guide covers keeping one around. Your Whitelist List May Not Show Everyone Who Can Join The second thing the documentation records and the notes do not is subtler and, for a server meant to be closed, more serious. The set of players the server enforces and the set the whitelist lists are not the same set. Two method descriptions on AccessControlModule say it outright. On listing, getUsersWithJoinGrant(): "A player who holds the permission through a group or a wildcard is not listed, because the grant belongs to the group rather than to them." On enforcement, isAllowedToJoin(UUID): "Answers the question the server asks when a player connects, so it counts a permission the player holds through a group or a wildcard as well as one granted to them." Put those side by side and the risk is plain. The listing shows direct grants. The door counts direct grants, group grants and wildcards. So a wildcard on a donor rank, or a staff group handed broad permissions long ago for convenience, can grant hytale.server.join to players who never appear in the whitelist listing. This failure mode did not exist before Update 6. The file used to be the answer; now it is one input among several, and only the enforcement question is trustworthy. Audit every group that carries a wildcard. Anything holding a broad grant now implies join access. This is the highest-value hour you can spend after updating. Treat the whitelist listing as a partial view. To know whether a specific player can get in, check the enforcement answer for that player, not the list. Push grants down, not up. A structure where broad permissions live in a few tightly held groups survives this change; one where a mid-tier donor rank quietly inherited a wildcard does not. Our rank system, permissions and donor perks guide covers building groups so a wildcard never becomes an accident. Watch the inverse too. Revoking a group can now remove join access from people you never meant to lock out. Anything that edits permissions is now something that edits access. The rest of the module is plainer: allowJoin(UUID) "Grants the player the permission they need to connect," its collection overload does the same for many players "as one change," disallowJoin(UUID) "Takes back the permission the player needs to connect," and disallowAllJoins() "Takes the permission back from every player that was granted it, as one change." The requirement itself is read and written through isJoinPermissionRequired and setJoinPermissionRequired. The batching matters if you migrate a large list programmatically. What Changed for Bans Bans were reworked in the same pass, on the same idea: fewer types, more places to plug in. The patch note reads "Ban handling is now one type. AbstractBan, InfiniteBan, and TimedBan collapse into a single codec-stored Ban." The documentation confirms it, describing Ban as "A ban on one player," with a CODEC field that is "The codec used to parse Ban instances." Any plugin that branched on which ban class it held needs rewriting. In exchange there are two clean extension points. BanProvider, which extends AccessProvider: "Holds the bans that the server applies when a player connects. The server runs a HytaleBanProvider, which stores the bans in a file. To keep the bans somewhere else, such as a database that several servers share, implement this interface and install it with AccessControlModule.setBanProvider(BanProvider). A method of this interface can block on the storage. Call it off the world thread." Two things there. First, a shared ban list across several servers is an explicitly documented use case, not a hack, so network-wide bans are a supported shape. Second, call it off the world thread. That warning is doing real work: a ban lookup hitting a database on the world thread stalls the world during exactly the condition you least want it to, a burst of connections. BanStorageProvider is the configuration-facing sibling: "The ban list named in the server configuration, which the server reads when it starts. A plugin that keeps the bans somewhere else registers its type with CODEC, so that a server can name it in its configuration. To install one without a configuration key, call AccessControlModule.setBanProvider(BanProvider) instead, which wins over what the configuration names." Write down the precedence rule in that last clause: setBanProvider wins over what the configuration names. If you are ever debugging a server that appears to ignore its own BanStorage configuration, a plugin calling setBanProvider is the first place to look. The built-in implementations are DiskBanStorageProvider, "A BanStorageProvider that keeps the bans in a file," and HytaleBanProvider, "A BanProvider that stores the bans in a JSON file." The patch notes add that the configuration can name ban storage under a BanStorage block "which is decoded after the plugins load". They do not say where that block sits, and we will not invent a path. Read your own generated configuration after updating. Applying a ban is described on the module as "Stores the Ban, then disconnects the target if they are online." Bans usually sit next to detection, and our anticheat plugin comparison covers the tooling that generates most of them. For Plugin Developers Three changes, one of which finally has an official explanation. The patch note: "Commands now declare their permission up front. canGeneratePermission has been removed, so a command that overrode it to return false must call requireNoPermission() instead. The HytalePermissions constants also changed from String to PermissionQuery, and code that needs the node string calls getId()." The canGeneratePermission removal is mechanical: find the overrides that returned false and call requireNoPermission() instead. The type change is the one that sprays errors across a build, because a constant going from String to PermissionQuery breaks every place you passed it where a string was expected, logging and config writing included. Add .getId() where you need the node text. What the notes never explain is why. The class documentation for HytalePermissions does: "A class containing all hard-coded Hytale permissions, for ease of reference. Each constant auto-registers with its associated permission group(s) via PermissionsModule.registerPermission(String, String...), and carries the lookup for its node rather than the node alone, because building one costs an order of magnitude more than asking a permission set with it. Call getId() where the node itself is needed." So it is a performance change, and a large one by the docs' own account: a PermissionQuery is a prepared lookup you hold once and reuse, rather than a string rebuilt into a lookup on every check. A real win on any hot path, once you are compiling again. The field that matters here is SERVER_JOIN, one of the 25 PermissionQuery constants on the class; the remaining three fields, NAMESPACE, COMMAND_BASE and EDITOR_TOOL_BASE, are still plain Strings. One limit worth stating honestly: the Javadoc does not publish the literal node string for SERVER_JOIN. The string hytale.server.join comes from the patch notes, a perfectly good source, but the constants are objects rather than string constants and the published constant values do not include it. If you are working through a wider Update 6 port, this break is one of several and rarely the worst. Our Update 6 protocol breaking changes guide covers the other large cluster. Migration Checklist for Server Owners Copy whitelist.json off the server before you update. A copy, not a rename. Check your plugin list for HytaleWhitelistProvider. Removed, not deprecated: anything implementing it will not compile and will not load. Same for InfiniteBan, TimedBan and BanParser. Update, then confirm whitelist.json.migrated exists. If your whitelist was populated and that file is missing, stop and investigate. Test with a non-operator account. Operators pass regardless, so they prove nothing. Audit every group holding a wildcard or broad grant. Any of them may now imply join access to a server meant to be closed. Do not use the whitelist listing as your access audit. It omits grants held through a group or a wildcard, by documented design. If you enable the requirement fresh, grant first and enable second, or you will refuse everyone. Network operators: look at BanProvider for a shared ban list, and keep the storage calls off the world thread. How much of this lands on you depends on where the server runs: a managed host handles some of the update and backup steps, a self-hosted box none. Our self-hosted versus managed hosting guide compares which parts are yours. Once access control is right and the doors are open to the right people, the next problem is getting people to walk through them. Browse the Hytale server list on HytaleCharts to see what is running, or add your own and start collecting votes. FAQ Why did my Hytale whitelist stop working after Update 6? Because the server no longer reads whitelist.json. HytaleWhitelistProvider was removed and whitelisting now runs on the hytale.server.join permission. On first start after the update your existing whitelist.json is renamed to whitelist.json.migrated and its entries move into permission grants. The commands still work; only the storage changed. How do I whitelist a player on a Hytale server now? With the same commands as before. The server exposes add, remove, list, enable, disable, status and clear as a whitelist command collection, and adding a player now grants them hytale.server.join rather than writing a line to a file. The documentation names the command classes but not the literal syntax, so check the exact form in your own console. Why is nobody able to join my Hytale server after enabling the whitelist? That is documented, expected behaviour. JoinPermissionProvider states that the permission belongs to no group, so a server that turns the requirement on refuses everyone until it grants it. Grant join access first, then enable the requirement. An operator keeps their way in because the admin group holds every permission, so testing as an operator will not reveal the problem. Does the Hytale whitelist list show everyone who can join? No, and this is the most important audit point in the change. The documentation states that a player who holds the permission through a group or a wildcard is not listed, while the check the server runs when a player connects counts group and wildcard grants as well as direct ones. Audit your permission groups, not just the listing. What happened to Hytale ban types in Update 6? AbstractBan, InfiniteBan and TimedBan collapse into a single codec-stored Ban. BanParser was also removed, which no patch note mentions and which is visible only in the API diff. Plugins can now implement BanProvider to replace ban handling or BanStorageProvider to store bans elsewhere, including a database shared across several servers. Installing a provider with setBanProvider wins over whatever the configuration names. What Hytale build is this, and when does Update 6 go stable? The pre-release API documentation self-reports Hytale Server API 0.6.0-pre.12, against 0.5.4 on the stable documentation site. The Part 12 patch notes themselves still name no build number. There is no announced stable Update 6 release date; we track what is and is not confirmed in our Update 6 release date tracker. The Short Version Hytale's whitelist stopped being a list and became a permission. The commands survived intact, the file gets renamed to whitelist.json.migrated, and the two things most likely to bite you are in no patch note: switching the requirement on refuses everyone until you grant it, operators quietly excepted, and the listing does not show anyone holding join access through a group or a wildcard. Which means the real work after this update is not on the whitelist at all. It is on your permission groups. Go and look at the ones with wildcards before someone else does.