How to Write a Crash Report Submission Flow

Players expect games to crash occasionally. What they do not expect is silence afterward. A well-designed crash report submission flow turns a frustrating moment into a constructive one — the player feels heard, and you get the exact data you need to fix the problem. The difference between a studio that ships stable games and one that doesn’t is often not whether crashes happen, but how quickly they get diagnosed. That speed depends entirely on the quality of the data you collect at the moment of failure.

Hooking Into the Engine Crash Handler

Every game engine provides a mechanism for intercepting unhandled exceptions or fatal signals. In Unity, you register a callback on Application.logMessageReceived and filter for LogType.Exception. In Godot, you override _notification with NOTIFICATION_CRASH or use a custom set_exception_handler in your native extension. In Unreal, FCoreDelegates::OnHandleSystemError gives you access to the crash context before the process terminates.

The critical requirement is that your handler runs before the engine tears down. You have a narrow window — sometimes only a few hundred milliseconds — to capture the data you need. Do not try to render complex UI or perform network requests in this window. Instead, write everything to a local crash dump file and present the submission dialog on the next launch.

func _ready():
    # Register crash handler on game startup
    var crash_handler = CrashReporter.new()
    crash_handler.set_dump_path("user://crash_dumps/")
    crash_handler.capture_on_crash([
        "stack_trace",
        "system_info",
        "scene_tree",
        "recent_actions"
    ])
    crash_handler.enable_screenshot_capture(true)
    add_child(crash_handler)

The dump file should include the stack trace, the operating system and hardware specs, the current scene or level name, and a ring buffer of recent player actions. Store this as structured JSON so your backend can parse it without guessing at field boundaries.

Designing the Crash Dialog

When the game relaunches after a crash, check for pending dump files. If one exists, show a dialog before the main menu loads. The dialog needs to accomplish three things: acknowledge the crash with empathy, collect optional context from the player, and make submission feel effortless.

Start with a short, human message. “Sorry, the game crashed last time you played” works. Avoid technical jargon in the headline. Below the message, provide a text area where the player can describe what they were doing. Many players will leave it blank, but the ones who write “I was fighting the ice boss and used the fire spell right as the cutscene started” give you more diagnostic value than the entire stack trace.

Add two opt-in checkboxes: one for attaching the log file and one for attaching the screenshot. Both should default to checked but be clearly toggleable. Show a thumbnail preview of the screenshot so players know exactly what they are sharing. If the screenshot contains personal information visible on a second monitor, they can uncheck the box.

Finally, include a “Send Report” button and a “Skip” button. Never force submission. Players who feel coerced will leave negative reviews. Players who feel invited to help will submit detailed reports willingly.

Structuring the Crash Payload

The submission payload should be a multipart form request. The primary body is a JSON object containing the crash metadata. File attachments — the log file and screenshot — ride alongside as separate parts. This structure keeps the metadata machine-parseable while allowing large binary attachments without base64 encoding overhead.

// Crash report payload structure
{
  "crash_id": "a7f3e2b1-4c89-4d12-b5a6-9e8f7c6d5e4a",
  "game_version": "1.2.3",
  "platform": "windows",
  "os_version": "Windows 11 23H2",
  "gpu": "NVIDIA RTX 3060, driver 551.23",
  "ram_mb": 16384,
  "scene": "IceCaveBoss",
  "stack_trace": "NullReferenceException at BossAI.cs:142...",
  "recent_actions": ["cast_spell:fire", "dodge_roll", "open_inventory"],
  "player_description": "Used fire spell during cutscene transition",
  "includes_log": true,
  "includes_screenshot": true,
  "timestamp": "2026-04-10T09:14:32Z"
}

Generate a unique crash ID client-side using a UUID. This prevents duplicate submissions if the player accidentally taps “Send” twice, and it gives you a correlation key that the player can reference if they follow up on your Discord or support channel.

Handling Submission Failures Gracefully

The player’s internet connection may be down when the crash dialog appears. Your submission code needs a retry strategy that does not block the player from entering the game. Send the report on a background thread. If the request fails, save the payload to a queue directory. On subsequent launches, check the queue and attempt to send any pending reports silently in the background.

Set a maximum queue depth of five to ten reports. If the queue is full, discard the oldest report. This prevents a scenario where a player with a recurring crash and no internet connection accumulates hundreds of unsent reports that all fire simultaneously when connectivity returns.

On the backend, deduplicate incoming reports by crash ID. If the same ID arrives twice, acknowledge it with a 200 response but do not create a second entry. This keeps your dashboard clean and your crash counts accurate.

Privacy and Player Trust

Crash reports can contain sensitive information. A screenshot might show a player’s desktop. A log file might contain file paths that reveal a username. A system info dump might include hardware serial numbers. Be deliberate about what you collect and transparent about how you use it.

Link to your privacy policy from the crash dialog. State plainly that the data is used only to fix bugs and is not shared with third parties. Strip file paths of username directories before submission — replace C:\Users\JaneDoe\AppData with C:\Users\[user]\AppData on the client side. Never collect IP addresses from the crash payload itself; if your backend logs them from the HTTP request, hash or discard them within 24 hours.

“We added a crash submission dialog after our early access launch. Within the first week, three players described the exact sequence of inputs that triggered our save corruption bug. Without their descriptions, we would have been hunting through stack traces for months. The dialog paid for itself in the first seven days.”

Related Issues

For guidance on structuring your log files so they are useful when attached to crash reports, see best practices for error logging in game code. To learn how to aggregate and triage incoming crash reports on your dashboard, read automated crash reporting for indie games. For mobile-specific considerations around crash capture and background submission, check out automated bug reporting for mobile games.

Add the crash dialog to your next build and playtest it yourself. Intentionally trigger a crash, relaunch, and fill out the form. If anything feels awkward, your players will feel it too.