Hytale Updated April 27, 2026

Managing Bans on Your Hytale Server

How to ban and unban players on your Hytale dedicated server using bans.json.

HytaleBansbans.jsonModerationAdmin

Managing Bans on Your Hytale Server

Hytale stores ban records in bans.json in the server root directory. Bans can be issued via in-game commands (by players with the server.ban permission) or by editing the file directly.

The bans.json File

bans.json is a JSON array of ban objects. Each entry contains the banned player's UUID, display name, the reason for the ban, and optionally an expiry timestamp.

[
  {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "BadActor",
    "reason": "Griefing",
    "bannedBy": "AdminPlayer",
    "bannedAt": "2026-04-20T14:30:00Z",
    "expires": null
  }
]

A null value for expires means the ban is permanent. To set a temporary ban, provide an ISO 8601 timestamp:

{
  "expires": "2026-05-01T00:00:00Z"
}

Issuing a Ban In-Game

Players with the server.ban permission node can use the ban command from within the game. The exact syntax depends on your server's command configuration, but the typical form is:

/ban <playername> [reason]

This writes a new entry to bans.json automatically.

Banning a Player via bans.json

To manually add a ban:

Stop the server (recommended to avoid file conflicts).
Open bans.json.
Add a new entry to the array.
Save the file and restart the server.

[
  {
    "uuid": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
    "name": "TroubledPlayer",
    "reason": "Repeated harassment",
    "bannedBy": "ServerAdmin",
    "bannedAt": "2026-04-27T10:00:00Z",
    "expires": null
  }
]

Unbanning a Player

To lift a ban, remove the player's entry from bans.json and restart the server. If the player is currently connected (on a different account, for example), they will not be affected until their next connection attempt.

Alternatively, if the server is running and you have in-game admin access:

/unban <playername>

This removes the entry from bans.json immediately without requiring a restart.

Viewing the Ban List

cat /opt/hytale-server/bans.json

For a formatted view:

python3 -m json.tool /opt/hytale-server/bans.json

Temporary Bans

To create a time-limited ban, set the expires field to a future UTC timestamp in ISO 8601 format. The server checks this value on each connection attempt and will automatically allow the player back once the timestamp has passed.

{
  "expires": "2026-05-07T12:00:00Z"
}

Finding a Player's UUID for Banning

If the player has previously connected, their UUID is in the server log and in the universe/players/ directory. If you need to ban a player who has never connected, obtain their UUID through the Hytale platform's player lookup tools.

Back to Knowledgebase

Need help? Submit a Ticket →

Managing Bans on Your Hytale Server