Troubleshooting and Known Limitations
Anomaly writes operational messages to the normal LabAPI server log. There is no separate public diagnostic stream or diagnostic toggle in v1.
Startup is not enough
Section titled “Startup is not enough”Require the “Anomaly.Server enabled; authenticated admission is operational.” log entry. A mandatory hook or service failure prevents admission even if LabAPI continues running. Companion plugins can check Anomaly.Server.Plugin.Instance?.IsOperational.
Anomaly must load before facility generation. If the log reports that a map already exists, restart the server process with Anomaly installed. A plugin reload after generation cannot establish the required authenticated snapshot.
When diagnosing startup or teardown, preserve the first initialization failure and any rollback or retained-patch errors. If Anomaly retains deny-all hooks because cleanup cannot be verified, restart the process before accepting players again.
Facility generation
Section titled “Facility generation”A generation error prevents clients from entering a mismatched map. Check the server’s generation log and any companion using FacilityLayout or MapEvents.LayoutFinalizing. Layout edits belong to the generation event windows; late calls and retained room-descriptor setters are rejected. Invalid poses, conflicting plugin edits, or unsupported layout topology need to be corrected before the next generation.
Join rejection
Section titled “Join rejection”Common causes include:
- Vanilla client or incompatible protocol release.
- Client identity profile failed to initialize.
- Identity rollback or competing rotation fork.
- Required password mode on a remote connection.
- Raw traffic or invalid-envelope rate limit exceeded.
- Server authentication/networking feature health is not operational.
Use the player’s server-local @anomaly ID from the server log or anomaly.whoami when correlation is possible. Never request user.json.
Reverse proxies and IP passthrough
Section titled “Reverse proxies and IP passthrough”Anomaly v1 intentionally uses the connection’s socket address and disables the game’s trusted-proxy IP-passthrough mode while the plugin is operational. The v5 handshake has no forwarded-address field. Do not place multiple public players behind a single forwarding endpoint when you depend on per-IP admission limits or forwarded-address bans; use a direct listener for this release.
Content problems
Section titled “Content problems”If a player cannot receive a custom item, inspect CustomItems.GetPlayerReadiness:
| State | Meaning |
|---|---|
| Unknown | No current offer is known. |
| Offered | The catalog was offered. |
| Approved | The tuple was approved. |
| Transferring | Missing allowed files are transferring. |
| Transferred | The approved files passed transfer validation; client materialization and activation are still pending. |
| Declined | The player declined; zero item content activates. |
| Activated | The exact catalog is active and grants may proceed. |
| Failed | Transfer or atomic materialization failed. |
A changed file affects offers for future player instances. Reconnect or native round restart receives the rebuilt catalog; a changed consent tuple requires approval again. Do not expect mid-round hot reload.
Password limitation
Section titled “Password limitation”Public password access is unavailable. RequirePassword=true must reject remote clients. Do not troubleshoot this as a wrong-password prompt; disable the requirement or keep the explicitly enabled legacy mode on loopback only.
Reporting a server issue
Section titled “Reporting a server issue”Include the server log around the failure, LabAPI and Anomaly versions, dependency/package hashes, other loaded plugins, exact reproduction steps, and whether the scenario was a clean start, round restart, process restart, or disable.