Troubleshooting

Troubleshooting

Start with the exact disconnect message and the server log lines from the same connection. The player's screen often gives less detail than the console.

Collect the basics first

• Server: Minecraft/Paper version, Java version and ModSeeker filename.
• Client: Minecraft version, Hidder filename, Fabric Loader version and Fabric API filename.
• Policy: normal, advanced or launcher-only; any player/Floodgate bypass.
• Failure: before Minecraft opens, before Hidder presence, during verification, or after a policy decision.

/modseeker status shows settings and counts. Compare it with the files you edited; a different instance or old plugin copy can explain an apparent config change that had no effect.

Minecraft fails before joining

Symptom	Check and action
Fabric says Hidder needs another Loader version	Select 0.19.3, 0.19.5 or 0.20.1 in the launcher. Fabric Loader is not the Fabric API JAR.
Fabric reports a missing dependency or wrong Minecraft version	Use Hidder for the exact Minecraft target and Fabric API for that target. Remove older duplicate Hidder JARs.
Java/class-version error	Match the Java level in Installation and Compatibility. Check the Java executable selected by the launcher, not just the Java installed globally.
Hidder reports native initialization or extraction failure	Confirm Windows x64, the intended JAR and a writable normal user temp directory. Save the actual client log error and check any quarantine event before replacing the download from an official source. Do not disable antivirus as a workaround.

Hidder presence or verification fails

Missing Hidder: confirm the JAR is in the instance you actually launched. Check that the client loaded it successfully. If a proxy is involved, verify that the connection reaches the intended backend and that the verification plugin channel is not being filtered.

Client update required / protocol mismatch: update ModSeeker and Hidder together. v3 uses protocol 3.6; check the actual installed releases on both sides.

Invalid client verification: compare the source of both JARs. An official server plugin and an independently generated custom client pair do not share the same client identity. Use the matching pair; changing the server's encryption keys does not repair that mismatch.

Security verification failed: read the preceding server reason and the client log. First rule out mixed builds, native initialization errors and unsupported Loader versions. This message is not proof that a player cheated. If the exact supported combination still fails, provide the redacted logs in a support report.

Mod-report or launcher timeout: check whether the client froze or logged an earlier native error. Test without proxy filtering if you control a test route. Increase a timeout only if the client is otherwise completing the check slowly; extra time will not repair missing dependencies or a wrong build.

A policy rejects the player

Symptom	Check and action
A mod ID is blocked	Inspect /modseeker modblacklist show. Check whether the ID is a bundled dependency used by an installed mod. Remove the intended rule or change the client, then reconnect.
Unauthorized mods in advanced mode	One or more file hashes are unapproved. Review the exact files and import intended ones through the GUI, bucket or a reviewed player report. A matching mod name/version label alone is insufficient.
Mod Verification Failed	Check for list-load warnings, an empty/unavailable advanced allowlist, or unidentifiable mod metadata. Restore valid policy files; do not clear them just to suppress the message.
Mod count exceeded	Compare the reported top-level ID count with maxModCount. Nested dependency count and folder file count are different measurements.
Launcher not allowed	Check the detected label, its client-list.yml entry and allowUnknownClients. All generated launcher entries start disabled.
Both verification checks are disabled	Enable at least one check. This combination denies non-bypassed players rather than making the server unrestricted.

Shared bundled dependencies can legitimately appear in more than one JAR. For a duplicate-identity error, first distinguish a Fabric startup conflict from a ModSeeker report error. Check for old copies of the same mod when Fabric reports an installation conflict. For a ModSeeker error, use the current matched v3 builds and record the precise server reason and affected versions if it persists. Do not remove valid bundled libraries at random.

A change seems to do nothing

• Config or client-list edit: use /modseeker reload, then read preceding warnings.
• Command or GUI policy edit: check its result; successful changes save directly. Ask the player to reconnect.
• New plugin JAR: stop and restart Paper. ModSeeker reload does not load a different binary.
• No mod list or seek cache: check ModVerification, bypasses and whether the client submitted a valid report. seek mod also requires the player online.
• An online player still joins after a test rule: check the active mode, the actual reported ID/hash and both bypass types. The blacklist is dormant in advanced mode.

GUI access fails

Symptom	Check and action
No usable link	Run modseeker gui in the server console. For a failed start, read GUI server failed to start: and the reason that follows.
Link opens localhost on the wrong computer	Blank externalUrl is local to the server's network namespace. Use a remote HTTP origin or the documented HTTPS proxy setup.
Connection refused / timeout	Check the listener's configured port, hosting/container allocation, host firewall and router TCP mapping. Setting externalUrl does not create those mappings.
Address already in use	Choose a free, separately allocated GUI port. Do not reuse Minecraft's TCP listener port.
Public URL fails only inside your LAN	Try another network. Some routers cannot route a LAN device back through the router's own public address.
HTTPS proxy returns an error	Confirm the proxy can reach the same-namespace 127.0.0.1 listener, its certificate/DNS are correct, and it preserves the configured public host.
Panel loads but actions are denied	Use the complete current link including its # token, with the configured origin. Avoid changing hostnames in the printed link.
Panel says unavailable after reload or some time	Run the console GUI command again. Sessions end on reload, timeout and closure of the last active panel tab.

See Web GUI for complete examples. The HTTP encryption warning is not a startup-failure message.

Bedrock players are asked to install Hidder

Bedrock players cannot install Hidder. ModSeeker skips verification when allowFloodgate is enabled and the Floodgate API identifies the connection as Bedrock.

1. Check allowFloodgate: true in ModSeeker's config. Run /modseeker reload after changing it.
2. Confirm Floodgate is installed and enabled on the Paper backend running ModSeeker. Geyser alone, or Floodgate only on the proxy, is not enough.
3. If players connect through Velocity or BungeeCord, set send-floodgate-data: true in the proxy's Floodgate config. The proxy and backend must use the same Floodgate key.pem; copy it privately from the proxy's Floodgate folder to the backend's Floodgate folder.
4. After changing the Floodgate setup, restart the proxy and backend, then reconnect the Bedrock player. ModSeeker should log bypassed verification via floodgate instead of starting a Hidder handshake.

Floodgate can be installed on both servers while the backend still lacks the forwarded Bedrock data. Receiving the player's UUID does not confirm that this API lookup will succeed. Follow the official backend setup instructions; never share key.pem in a support report.

If the problem remains, check the startup log for Floodgate availability or API errors and include those lines in a redacted report. See Floodgate and Bedrock.

Discord alerts do not arrive

For missing Discord alerts, check the master/event switches, valid webhook URL and outbound HTTPS. Some events occur only after mod verification passes. See Discord Alerts before assuming delivery failed.

If the issue remains, use the report checklist in FAQ and Support.