Crash Reporting for LÖVE (love2d) Games

LÖVE, often written love2d, is a beloved framework for making 2D games in Lua, and it has a distinctive crash behavior: when an unhandled Lua error occurs, LÖVE shows its built-in error screen, the famous blue screen with the error message. That screen is helpful for the developer running the game locally, but for a player it is a dead end, they see an error and close the game, and you never learn what happened. Setting up crash reporting for a LÖVE game means hooking that error path to capture and upload the error rather than just displaying it.

LÖVE catches errors with an error handler

When a Lua error propagates unhandled in a LÖVE game, the engine catches it and calls its error handler, which by default displays the error screen with the message and a traceback. This is actually a useful design, because it gives you a single, well-defined place to hook: love.errorhandler. By overriding it, you control what happens when the game crashes, including capturing and sending a report.

This is cleaner than crash handling in many environments, because LÖVE has already caught the error and assembled the message and traceback for you. Your job is to take that information, which the engine hands to your error handler, and get it off the player machine instead of only showing it on screen. The error handler is the natural and reliable hook for LÖVE crash reporting.

Override love.errorhandler

The core of LÖVE crash reporting is overriding love.errorhandler with your own function. When a crash occurs, your handler receives the error message, captures the traceback using Lua debug facilities, packages them into a report with context, and uploads it, then optionally displays a player-friendly message rather than the raw error screen.

Capture the full traceback, not just the error message, because the traceback shows the call path through your Lua code to the line that errored, which is what you need to find the cause. Lua tracebacks are readable and point directly at your source, so a LÖVE crash report with a good traceback is immediately actionable. Replacing the default error screen with capture-plus-a-friendly-message turns the crash from a dead end into both a report for you and a better experience for the player.

Use pcall for recoverable risks

Beyond the global error handler, Lua pcall lets you call risky code in a protected context that catches errors without crashing the whole game. For operations that might fail but should not be fatal, loading a file, parsing data, calling into a library, wrapping them in pcall lets you handle the error gracefully and report it, while keeping the game running.

Use pcall to capture non-fatal errors as reports without taking down the game, complementing the global error handler that catches the fatal ones. This gives you visibility into recoverable problems, a failed asset load, a data parse error, that the player might not even notice but that indicate bugs worth fixing. Together, the global error handler and targeted pcall capture both the crashes and the handled errors, giving you a fuller picture of what is going wrong in your LÖVE game.

Capture platform and version context

LÖVE runs across Windows, macOS, Linux, and mobile, and a crash can be platform-specific. Capture the platform, the LÖVE version, and your game version with every report, because a crash that only appears on one platform or one LÖVE version points at a platform or engine-version issue rather than a general bug in your Lua code.

LuaJIT, which LÖVE uses, can also behave subtly differently across platforms, so the platform context helps interpret performance and edge-case crashes. Capturing the LÖVE version is especially useful because behavior changes between engine versions, and a crash tied to a specific version tells you whether an engine update introduced or fixed the issue. The platform and version context turns a bare Lua error into one you can place in its environment.

Setting it up with Bugnet

Bugnet works with LÖVE by overriding love.errorhandler to capture the Lua error and traceback and upload them, with the platform, LÖVE version, and your game version attached. Instead of the player hitting the default error screen and closing the game, the crash is reported to your dashboard, and you can show a friendlier message, turning the crash into both data and a better player experience.

Add custom fields for your game state, and use pcall-based reporting for recoverable errors so handled problems surface too. Group identical errors into occurrence counts to prioritize, and because Lua tracebacks point directly at your source, your LÖVE crashes are readable and actionable straight from the dashboard, which is exactly what you need to keep a Lua game stable across the platforms it ships on.

Improve the player-facing error experience

LÖVE crash reporting is a chance to improve not just your visibility but the player experience of a crash. The default error screen is fine for development but jarring for players, so when you override the error handler to capture the report, also replace the raw error with a clear, friendly message: something went wrong, the report has been sent, here is how to recover. This turns a crash from a confusing dead end into a handled, reassuring moment.

Offer the player a path forward where you can, a restart, a return to menu, a note that you have been notified, so the crash feels managed rather than catastrophic. Combined with the automatic report, this means every LÖVE crash both informs you and treats the player with care, which is a meaningful upgrade over the default behavior and exactly the kind of polish that distinguishes a finished LÖVE game from a prototype, especially as Lua tracebacks make the resulting reports so easy to act on.

LÖVE hands the error to your handler. Send it onward instead of just painting the blue screen.