Crash Reporting - Refinery WIKI

xyz.refineryteam.refinerycore.api.crash turns raw stack traces into actionable reports. A CrashHandler matches thrown exceptions against registered CrashHints — each hint recognizes a class of failure and carries a headline, extracted context fields, and human guidance lines (“what you can try”) printed alongside the stack trace. Plugins extending RefineryPlugin receive a handler from onLoad() through getCrashHandler(). RefineryCorePlugin uses that handler for failed startup steps and configuration reloads, and registers default hints for database, I/O, missing-class, API mismatch, illegal-state, and null-pointer failures.

Every report line goes through the plugin’s Logger rather than raw stdout, so timestamps, thread names, and log levels stay intact — the report reads like any other server log output instead of an interleaved block.

Basic usage

MyPlugin.java

CrashHandler crashes = CrashHandler.of(this);

crashes.hint(CrashHint.of()
    .matchesType(java.sql.SQLException.class)
    .title("Database error")
    .context("SQL State", e -> e instanceof java.sql.SQLException sql ? sql.getSQLState() : null)
    .help(
        "1. Is the database reachable from this machine?",
        "2. Check database.username / database.password in config.yml.",
        "3. If using SQLite, verify the data folder is writable."
    )
    .build());

try {
    riskyDatabaseOperation();
} catch (Exception e) {
    crashes.report(e, "while saving player data");
}

A matching report prints a boxed headline, the exception message and root cause, any extracted context fields, the hint’s help bullets, and the full stack trace with causes. Reports are also appended to logs/refinery-crash-reports.txt for post-mortem reading, since console spam scrolls away.

`CrashHint`

Each hint is built fluently:

Builder method	Description
`matches(Predicate<Throwable>)`	Predicate deciding whether the hint applies — tested against the root cause of the reported exception
`matchesType(Class<? extends Throwable>)`	Convenience: match by exact class or subclass
`title(String)`	Headline shown at the top of the report box
`context(String key, Function<Throwable, String>)`	Extracts a contextual value from the throwable (e.g. SQL state, failing host); rendered as `key: value` lines. Failing extractors never break report generation
`help(String... lines)`	Human guidance lines rendered under “What you can try” when the hint matches
`build()`	Returns the finished hint

Register more specific hints before general ones — the first matching hint wins, and a report without any matching hint falls back to a generic "Unhandled exception" headline.

`CrashHandler`

Method	Description
`CrashHandler.of(plugin)`	Creates a handler bound to your plugin’s logger and data folder
`hint(CrashHint)`	Registers a hint; returns the handler for chaining
`report(Throwable)` / `report(Throwable, String where)`	Reports an exception, optionally with a short description of what was happening (e.g. `"while running riskyOperation"`). `null` throwables are silently ignored
`withoutFileLogging()`	Disables writing to `logs/refinery-crash-reports.txt`; reports only go to the console log

Wrap report(...) calls around the operations most likely to fail at runtime — database access, web requests, file I/O. Since hints carry the troubleshooting steps, this is also a good place to encode knowledge that currently lives in your head or your support Discord.

​Basic usage

​CrashHint

​CrashHandler

Basic usage

`CrashHint`

`CrashHandler`