Troubleshooting

The console shows no setup link

The link is printed only while there is no Owner account. If you already created one, sign in. If nobody can sign in anymore, run /ac resetowner in the server console.

The panel does not open

Check /ac version: it shows the panel address, or why it did not start (for example a port in use).
On a hosting panel, use a port your host gives you for web.port and open that port. Without a reverse proxy the panel is then on plain HTTP, readable by anyone on the network: see Panel over HTTPS.
Behind a reverse proxy, web.host: 127.0.0.1 makes the panel reachable only through the proxy.

After 5 wrong passwords from one address the account waits 15 minutes on that address (IPv6 addresses count by their /64 network); you can still sign in from another one. After 50 wrong passwords from any addresses the account waits 15 minutes everywhere. On a network sharing one MySQL database these counts (and the limits on 2FA codes) are shared by every server's panel within about 2 seconds. Wait, or let another Owner check Audit log for auth.login entries with the result denied and the address they came from. Behind a reverse proxy, add the proxy under Settings → Server → Security → Trusted proxies, or every entry shows the proxy's address.

Links in game point to the wrong address

Set web.public-url to the address you open the panel at and restart.

The live parts of the panel do not update

Your reverse proxy must pass WebSocket upgrades (see the Nginx example in Panel over HTTPS).

Commands from another plugin are taken over

With punishments.shortcuts: true AdminControl registers /ban, /mute and others only where no other plugin already did. Set it to false and restart to leave them all to the other plugin; /ac ban always works.

RCON shows no reply to punishment commands

Punishment commands answer after the database write, when RCON has already answered. The punishment is given; see it in the panel, the audit log or the server log.

Warnings at start with MySQL or MariaDB

Two lines Unknown system variable 'WSREP_ON' at start are harmless: the migration tool checks for a database cluster.

Velocity: every player has the address 127.0.0.1

The servers do not get the players' real addresses from the proxy. Turn on modern forwarding with a secret on the proxy and on every server: Velocity network, "Modern forwarding".

Velocity or BungeeCord: the proxy does not enforce punishments

The proxy log says needs the shared MySQL/MariaDB database: set database.type: mysql in plugins/admincontrol/config.yml (Velocity) or plugins/AdminControl/config.yml (BungeeCord) on the proxy, with the database the servers use.
A punishment from one server does not reach the others: every server must use the same MySQL or MariaDB database (not SQLite). /ac version on the proxy shows how far it has read the punishment log; the number grows with each new punishment.

AdminControl does not load after the first start or an update

On the first start with this version, the server downloads the Adventure libraries AdminControl lists from Maven Central (Paper, Purpur and Folia too, though only Spigot uses them). Without internet access it logs an error about net.kyori libraries and skips the plugin. Start the server once with outbound access, or copy the libraries/ folder from a server where it worked and check it against the sums in Install and first start, "On Spigot".

Spigot: MSPT shows "–"

Spigot does not report how long a tick takes, so the dashboard shows TPS (from AdminControl's own tick counter) and no MSPT. This is expected.

BungeeCord: AdminControl does not load on the proxy

On its first start with AdminControl, BungeeCord downloads the Adventure libraries from Maven Central. Without internet access it logs an error about net.kyori libraries and skips the plugin. Start the proxy once with outbound access, or copy the libraries/ folder from a proxy where it worked; very old BungeeCord builds cannot load these libraries and need an update (BungeeCord network).

"Unsecured forwarding" or "without BungeeGuard" warning

The server is in BungeeCord mode (settings.bungeecord: true in spigot.yml) without BungeeGuard. Anyone who can reach its port directly can join as any player. Close the port to everything but the proxy, or install BungeeGuard on the proxy and the servers: BungeeCord network, "Securing the servers". With a firewall in place the warning stays, as AdminControl cannot see firewall rules.

"checked against the in-memory list" in the log

The database did not answer the ban check of a joining player within 3 seconds, so the bans AdminControl keeps in memory decided: a banned player is refused, anyone else gets in. The list in memory is read again every 5 minutes. Many of these lines in a row mean the database is overloaded or unreachable; check its connection and load.

The network panel shows a server as "Conflict"

Two running servers use the same server-name, or the same id in plugins/AdminControl/server-id (a copied server folder). See Network panel, "Conflicts and copied folders".

"survival did not receive it" after a command in the console

The server did not take the command within 30 seconds: it was stopped, frozen, or cannot reach the database. The command is not run later. Check that server's console for database errors, then send the command again once the server shows as online in the network list.

Known limitations

Small behaviours that are known and accepted for this version. None of them loses data or weakens access control.

Panel

After an expired session, a page opened in another tab keeps its data until it reloads.
The 2FA code field loses focus after a wrong code; screen readers are not told the field is invalid.
The mobile "More" sheet does not trap focus and does not return focus to its button when closed.
A rate-limited answer does not show how many seconds to wait.
The punishment list's player filter matches the exact name only.
The chat "to" filter works to the minute: messages in the seconds after it are left out.
The unread counter of private messages keeps counting messages from before the switch was turned off, and grows while the reader stays scrolled up.
Some switch texts are not clickable labels.
An expired reporting block stays visible until the list refreshes.
A note rejected by the server shows the generic error instead of the field message.
"Send test" uses the saved webhook even while a new, unsaved address is typed.
An unsaved role order is not reset when the roles change after a refresh (saving then answers 422).
Moving between pages after a role change uses the old role until the session refreshes.

A pending 2FA app change has no expiry of its own (it ends with the challenge).
Two enrolments of one invite at the same moment, with codes from neighbouring 30-second steps, can remove the first account (needs the account's own 2FA secret).
Missing fields in the sign-in request answer 422 where a wrong password answers 401.
Public invite and reset requests check their fields before the link (422 on a dead link instead of 404/410).
A sign-in that succeeds but cannot end the browser's previous session reports an error while the new session works.
A session's device fields are left out (not null) when the browser or system is unknown.

Players and punishments

Creating a punishment does not also require players.view (a custom role with punish.ban only can punish by UUID).
An unknown players filter value returns all players.
A very fast reconnect on MySQL can open two sessions and count the overlap twice in playtime.
Failed skin downloads are not cached, so a slow Mojang answer is retried on every request (5 s each).
/ac punish shows the step from its own preview, which can differ from the stored one when two staff act at once.
A template deleted while a command uses it is reported as an unknown player.
Templates and rules API check the body before the permission (422 before 403).

Chat

The default private-message commands are msg, tell, w, whisper, pm, emsg, etell, ewhisper; servers with other aliases add them in config.yml.
A slow-mode-only change also tells players the chat state changed.
Messages sent from the panel may contain line breaks.
Private messages are deleted by a full scan on very long chat histories (no index on channel and time).

Console and announcements

Custom roles with console.view see player IPs and private messages in the console output, whatever their other permissions.
A manual announcement and the rotation in the same second, or an edit racing a send, can send it twice.
announcements.send is audited before the send has succeeded.
The console prefix of panel commands is not grey as in the preview.
Punishment commands sent over RCON show no reply (it comes after the database write, when RCON has already answered); the result is in the panel, the audit log and the server log.
/ac whitelist off and /ac resetowner run only from the server console itself, not over RCON or the panel console.
On Folia, vanilla commands from the panel console that act on entities outside the global region may be refused by Folia; plugin commands and /ac work.

Team and audit

Role changes use the actor's role from the start of the request (a demotion at the same moment is seen next time).
Reading a member's sessions audits without the request IP.
Team requests check the body before team.manage (422 before 403).
Role limits given as whole decimals (3600.0) are rejected.
The audit target filter also matches invite names.
Read audit entries (IP and private-message views) are written on every page load.

Settings and integrations

A settings change on another server sharing the database reaches this one within a minute.
The chat retention in config.yml accepts 1–365 days; the panel's minimum of 7 applies.
An hour of statistics averaged just before its last sample keeps 11 of 12 samples.
Discord: queued messages keep the webhook address from when they were queued; markdown list markers, -# and <@…> are not escaped.
LuckPerms: an unlink on one server and a relink on another can apply in reverse order (corrected within 10 minutes).
The TPS alert keeps its state while server-state messages are off.

Reports

Category words are matched with ASCII spaces only (a non-breaking space is part of the word).
The concurrent-claim behaviour is the same on SQLite and MySQL but is load-tested on SQLite only.
A report closed at the very moment its reporter leaves the game may not send them the closing message.

Import

Kicks show as expired (punishments panel rule); the preview in the mock showed them active.
LiteBans removal dates are read in the server's time zone.
Text is cut to the column sizes (reason 200, names 32 characters).
LiteBans server scope is not used: punishments of the whole network come in.
AdvancedBan in offline UUID mode (names instead of UUIDs) imports nothing.
The whole source is read into memory; networks with millions of LiteBans rows need a large heap.
Opening the Import page connects to the LiteBans/AdvancedBan databases (up to 5 s when one is down).

Velocity and BungeeCord networks

Tab completion of /ac on the network lists only the proxy commands.
Mutes are enforced by the servers, not by the proxy.
The proxy has no panel; the panel of any server reaches the whole network.
The "Unsecured forwarding" warning cannot see firewall rules: it stays on a server whose port only the proxy can reach.
BungeeCord needs internet access on its first start with AdminControl to download the Adventure libraries.

Operations

A corrupted server-id file is replaced without a warning. Cloned server folders share one id; the network panel shows them as a conflict.
If Paper's sampler methods fail, the dashboard shows 20 TPS and no chunk or entity counts.
Sockets without a session are not limited per address.
SQLite search is case-insensitive for all letters; the database itself still sorts names by code point.
With MySQL or MariaDB the database driver logs two harmless warnings at startup: Unknown system variable 'WSREP_ON' (a cluster check of the migration tool).
/ac reload does not apply web., database., punishments.shortcuts or the console, announcements, reports and import modules; it lists the keys that need a restart.