Paper Not Responding: What to Keep After a Watchdog Warning
When Paper stops responding and prints a watchdog warning, preserve the incident log, establish whether the process is still running, and prepare a controlled reproduction before changing timeouts. Your immediate goals are to restore a known operational state and retain enough evidence to investigate. A successful restart alone does not show that the fault is fixed.
This guide is for established community owners and teams handing an incident to their operator or developer. It covers prolonged hangs on Paper. The procedure and example are proposed working practices, not tests performed by Mineando; do not apply them automatically to Folia or a modded server.
Separate a warning from a shutdown
Paper explains that a watchdog warning can indicate a severely delayed tick while the process remains alive. A thread dump records where a thread was executing at that moment; it can guide investigation without necessarily exposing the cause. See Paper's troubleshooting documentation.
Record three things separately: what players experienced, what the server logged, and what the process manager did. A screenshot of the final line loses the sequence needed to connect them.
| Observed situation | Proposed first check |
|---|---|
| Warnings appear, but the process continues | Record whether responsiveness returns and when; a running process alone is insufficient |
| The process exits after warnings | Preserve the end of the log and establish which component requested the stop or restart |
| The process disappears without earlier warnings | Request host and process-manager events from the operator; leave the cause unresolved |
Do not classify every disconnection as a watchdog incident. Attach a timestamp and an identifiable evidence source to each observation.
Preserve an incident record before making more changes
Assign one person to coordinate the incident and record interventions. If the service remains stuck, follow the shutdown or recovery procedure agreed with your operator. Do not extend an outage indefinitely while trying to obtain a perfect capture.
Keep the following in a dated folder with an incident identifier:
- The affected run's log, complete warnings, and the surrounding entries. Include relevant rotated logs.
- The time and timezone, observed duration, and player actions immediately before the incident.
- Exact Minecraft, Paper, Java and plugin versions, plus the last known change.
- Relevant watchdog and restart configuration, with passwords and keys excluded.
- Available host events and metrics for that interval: memory, CPU, storage and external dependencies.
- Each intervention, its time and its outcome; explicitly mark evidence that could not be collected.
Retain an original under restricted access and prepare a reviewed copy for sharing. Preserve useful stack information when removing sensitive details. Sending an entire server directory or database credentials is unnecessary for documenting a hang.
If restoration is being considered, identify the recovery point and the progress that would be lost. A backup restore rehearsal helps prepare that decision. Restoring a copy does not establish why the incident happened.
Do not accept silence as a successful repair
Paper's global configuration reference defines watchdog.early-warning-delay as the delay before dumps begin and early-warning-every as their interval, both in milliseconds. It lists defaults of 10000 and 5000. Check your installation's actual values.
The spigot.yml reference documents settings.timeout-time in seconds, alongside restart-on-crash and restart-script. That restart mechanism does not cover an external termination by the operating system. Establish what else manages the process in your deployment.
These settings serve different purposes. Record their original state and the intended behavior change before editing them. Raising a threshold is not evidence that the operation holding up the server has improved.
Paper also documents disable.watchdog as disabling the warning system in its system-property reference. Do not accept a repair merely because that change removes the messages. If a specialist requires different settings during investigation, limit the experiment and document the final operating configuration.
Turn a stack trace into a testable hypothesis
Ask the reviewer to identify the thread and operation worth investigating, then explain what evidence is missing. A plugin name appearing in a trace is insufficient grounds for removing it. Connect that lead to the incident time, relevant dependencies and a reproducible action.
Consider a hypothetical incident: at 19:42 someone opens a rewards menu; warnings follow and gameplay stops advancing. The trace includes calls associated with that feature. The working hypothesis is that the action participates in the hang. It does not yet establish whether the plugin, a dependency or the environment is responsible.
On an isolated copy, reproduce that action using the same versions and representative state. Prevent the copy from writing to production databases or integrations. Ask the developer to propose one controlled variation, then repeat the scenario. Record runs that hang and runs that do not; one successful attempt cannot rule out an intermittent fault.
If an additional profile is needed, arrange the capture before reproducing the issue. Paper's profiling documentation says the problem must be occurring for profiling to be useful. A later profile of a quiet session cannot explain the earlier hang on its own.
Agree what permits reopening and what remains unresolved
Before retesting, agree the scenario, planned repetitions, expected outcomes and decision owner. Track service recovery separately from confirmation of the cause: they may happen at different times.
To accept a correction, request the original scenario record, the applied change, and the result when the scenario is repeated. Check the affected feature too: in the example, a reward should be delivered exactly once and its state should survive a clean restart. These are proposed checks for this scenario, not universal stability guarantees.
If the correction requires component updates, use a reopening and recovery decision with an identified release and a prepared recovery path. Keep the root cause unresolved when only a mitigation has been applied.
For a managed Minecraft infrastructure review, bring the incident record, its impact on your community, and the available rehearsal window. Mineando undertakes paid projects with individually agreed scope. Monitoring, maintenance and incident coverage are agreed explicitly; a review does not imply permanent availability.
