FailureToLog Paper Plugin

FailureToLog is a Paper server plugin that reports failed logins, error disconnects, and compatible Fabric client disconnect reports in server chat.

It helps server staff understand why a player failed to connect or was disconnected, then inspect a stored server-side error report through an in-game command.

What It Does

• Detects failed player login attempts.
• Detects server-side kicks and error disconnects.
• Changes error disconnect messages to a clearer FailureToLog message.
• Keeps normal join and normal quit behavior unchanged.
• Stores recent error logs for inspection.
• Adds clickable chat buttons for viewing error details.
• Receives client-side disconnect screen reports from the optional FailureToLog API Fabric mod.
• Provides commands for enabling/disabling the plugin, toggling log saving, viewing error codes, and opening stored logs.

Requirements

• Paper 26.1.2
• Java 25 or newer

Optional client companion:

• FailureToLog API Fabric mod for Minecraft 26.1.2

Installation

1. Stop the server.
2. Put the plugin jar into the server plugins folder.
3. Start the server.
4. The plugin will create its config and log files automatically.

Plugin jar:

FailureToLog-Paper-1.0-SNAPSHOT.jar

Typical server folder:

plugins/FailureToLog

Configuration

Config file:

plugins/FailureToLog/config.yml

Default config:

enabled: true
save-logs: true

enabled

Turns FailureToLog behavior on or off.

enabled: true

save-logs

Controls whether error logs are saved to disk.

save-logs: true

When enabled, logs are saved to:

plugins/FailureToLog/logs.yml

Commands

Main command:

/failuretolog

Alias:

/ftl

Toggle Plugin

/failuretolog toggle

Turns FailureToLog on or off.

Requires:

failuretolog.admin

Toggle Log Saving

/failuretolog savelogs <on|off>

Examples:

/failuretolog savelogs on
/failuretolog savelogs off

Requires:

failuretolog.admin

View Error Codes

/failuretolog codes

Shows the full FailureToLog error code list.

View Error Log

/failuretolog log <id>

Shows a stored error report.

When an error is detected, FailureToLog posts a chat message with a clickable [View error] button. Clicking that button runs this command automatically.

Permissions

failuretolog.admin

Default:

op

Allows changing FailureToLog settings with:

/failuretolog toggle
/failuretolog savelogs <on|off>

Chat Message Format

Example:

Due to an error, PlayerName failed to connect. Error code: 600 (Bad client data) [View error]

For server-side kicks:

Due to an error, PlayerName lost connection. Error code: 500 (Server-side problem) [View error]

For Fabric client reports:

Due to an error, PlayerName reported a client-side disconnect. Error code: 1 (Unknown crash) [View error]

Normal joins and normal quits keep the server's default behavior.

Error Codes

FailureToLog includes these codes:

1: Unknown crash
6: Not whitelisted
7: Banned
9: Blacklisted
105: World chunk load failure
200: Server memory shortage
201: Client memory shortage
401: Authentication/session failure
408: Connection timeout
429: Connection throttled
500: Server-side problem
503: Server full
600: Bad client data
601: Unsupported client version
602: Resource pack failure
790: Mod or socket conflict

The plugin classifies errors from login results, kick reasons, server messages, and optional Fabric client reports. If an error cannot be classified, it uses:

1: Unknown crash

Fabric Client Integration

FailureToLog can receive extra client-side disconnect information from the optional FailureToLog API Fabric mod.

The plugin uses these Minecraft custom payload channels:

failuretolog:hello
failuretolog:client_log

Flow:

1. Player joins the server.
2. Server sends failuretolog:hello.
3. Compatible Fabric clients detect the FailureToLog server.
4. If the client sees a disconnect screen, the Fabric mod stores the screen title and reason.
5. The mod sends the report to the server immediately or on the next connection, depending on the client's setting.
6. The server stores the report and posts a clickable chat message.

Important Limitations

A server plugin cannot directly read a player's local client logs or crash reports.

Without the Fabric client companion mod, FailureToLog can only use information visible to the server, such as:

• Login denial reason
• Kick reason
• Server-side exception wording, when available
• Player name
• UUID, when available
• Address, when available

With the Fabric mod installed, FailureToLog can also receive the client's disconnect screen title and reason.

Privacy Notes

FailureToLog stores server-side connection/error details.

Fabric client reports may include:

• Disconnect screen title
• Disconnect reason
• Minecraft version
• Player name
• Server address
• Timestamp
• FailureToLog protocol/plugin version

The system does not intentionally collect full local game logs or full crash reports.

Recommended Platform Description

Short description:

Paper plugin for reporting failed logins, error disconnects, and optional Fabric client disconnect reports in chat.

Long description:

FailureToLog is a Paper server plugin that helps staff understand why players failed to connect or were disconnected.

It detects failed login attempts and error disconnects, assigns an error code, stores a short server-side report, and posts a clickable chat message so staff can open the details with one command.

When paired with the optional FailureToLog API Fabric client mod, the plugin can also receive client-side disconnect screen details, giving staff more context than the server can normally see on its own.

Suggested Tags

• Paper
• Server plugin
• Admin tools
• Logging
• Error reports
• Connection diagnostics
• Fabric integration
• Moderation tools
• Utility

Build Output

Integrated distribution builds are copied to:

C:\Users\musek\IdeaProjects\dist

Paper plugin jar:

FailureToLog-Paper-1.0-SNAPSHOT.jar

Fabric client companion jar:

FailureToLog-API-Fabric-1.0.0.jar

Run the integrated build script:

C:\Users\musek\IdeaProjects\build-all-failure-to-log.bat