Fix: Godot Exported Game Crashes on Startup

Here is how to fix Godot exported game crashes on startup. Your game runs perfectly inside the Godot editor. You hit Export, launch the resulting binary, and it crashes instantly — no window, no error dialog, just a silent exit or a system-level crash report. This is one of the most frustrating moments in game development because the editor gave you zero indication that anything was wrong. The good news is that exported-game startup crashes almost always trace back to one of five specific problems, and every one of them has a concrete fix.

The Symptom

After exporting your Godot 4 project, the resulting executable crashes immediately on launch. Depending on the platform and the root cause, you might see a brief flash of a window that disappears, an OS-level crash dialog, or absolutely nothing at all. The game never reaches your title screen or main scene.

If you run the exported executable from a terminal, you might see error output before the crash. Common messages include ERROR: Can't open file from path 'res://...', ERROR: Failed to load resource 'res://addons/...', or FATAL: Condition !main_pack_loaded is true. Sometimes there is no output at all — just a non-zero exit code.

The confusing part is that everything works inside the editor. The game runs, the scenes load, the autoloads initialize. The crash only happens in the exported build, which makes it feel like the export itself is broken. In most cases, it is not the export process that failed — it is a configuration issue that only manifests outside the editor environment.

Missing or Mismatched Export Templates

The most common cause of immediate startup crashes is missing or version-mismatched export templates. Godot export templates are precompiled binaries for each target platform. When you export your project, Godot packages your game data and pairs it with the appropriate template binary. If no template is installed, the export fails outright. But if you have templates from a different Godot version, the export may succeed while producing a binary that crashes on launch.

Export templates must match your editor version exactly, down to the patch level. If your editor is Godot 4.3.1, you need templates for 4.3.1 — not 4.3, not 4.3.2. Even a minor mismatch can cause the binary to be unable to read the .pck data format, resulting in an immediate crash.

# Check your Godot version programmatically
extends Node

func _ready():
  var version = Engine.get_version_info()
  print("Godot version: %s.%s.%s.%s" % [
    version.major, version.minor,
    version.patch, version.status
  ])
  print("Build hash: ", version.hash)

To fix this, open Editor > Manage Export Templates and check the installed version. If it does not match, remove the old templates and install the correct ones. You can download templates directly from the dialog or from the Godot downloads page. For custom builds, you must compile the templates from the same source commit as your editor.

.pck File Issues

When Godot exports your project, it creates a .pck file containing all your game resources — scenes, scripts, textures, audio, and everything else in the res:// directory tree. The exported executable expects this file to be either embedded within it or sitting next to it with a matching name.

If the .pck file is missing, renamed, or corrupted, the game will crash on startup because it cannot load the main scene or any of the resources it needs to initialize. This happens when you move the executable without moving the .pck, or when you rename one without renaming the other.

# Verify .pck loading at the earliest opportunity
# Add this as your first autoload to catch .pck issues
extends Node

func _init():
  # If this code runs, the .pck loaded successfully
  var file = FileAccess.open("res://project.godot", FileAccess.READ)
  if file == null:
    OS.alert("Failed to read project.godot. The .pck file may be missing or corrupted.")
    get_tree().quit(1)
  else:
    print("Pack file loaded successfully.")

The fix is straightforward: ensure the .pck file is in the same directory as the executable and has the same base name. If your binary is mygame.exe, the pack file must be mygame.pck. Alternatively, re-export with the Embed PCK option enabled in your export preset, which bakes the data directly into the executable so there is no separate file to lose.

Autoload Paths Broken After Export

Autoloads are singletons that Godot loads before any scene. They are configured in Project Settings > Autoload using res:// paths. If an autoload path points to a file that does not exist in the exported build, the game crashes immediately because Godot cannot initialize its singleton list.

This happens most often when an autoload references a script or scene that was moved or deleted but the autoload entry was not updated. Inside the editor, the file might still be cached or resolved through editor-specific fallbacks, masking the problem. The exported build has no such fallbacks.

# Diagnostic: list all autoloads and verify they exist
extends SceneTree

func _init():
  var config = ConfigFile.new()
  var err = config.load("res://project.godot")
  if err != OK:
    print("Cannot load project.godot")
    return

  if config.has_section("autoload"):
    for key in config.get_section_keys("autoload"):
      var path = config.get_value("autoload", key)
      # Strip the leading * if present
      path = path.trim_prefix("*")
      var exists = ResourceLoader.exists(path)
      print("Autoload '%s' -> %s [%s]" % [key, path, "OK" if exists else "MISSING"])

To fix this, go through every entry in Project Settings > Autoload and verify each path is correct. Pay special attention if you recently reorganized your project folder structure. Also confirm that the referenced files are not excluded from the export by custom filter rules.

Custom Resources Not Exported

If your project uses custom resource files with non-standard extensions, Godot’s export process may not include them. By default, Godot exports all files with recognized extensions (.tscn, .gd, .tres, .png, etc.). But if you have data files with custom extensions — say .dat, .json, or .cfg for game configuration — they will be silently excluded unless you explicitly tell the exporter to include them.

When the game tries to load one of these missing files at startup, it crashes. This is especially common with custom resource types defined via class_name that are saved with the .tres extension but reference scripts that got excluded, or with data files loaded during autoload initialization.

# Safely load a custom resource with fallback
extends Node

const CONFIG_PATH := "res://data/game_config.cfg"

func _ready():
  if not FileAccess.file_exists(CONFIG_PATH):
    push_error("Config file missing: %s" % CONFIG_PATH)
    push_error("Add '*.cfg' to Export > Resources > Filters to Export Non-Resource Files")
    return

  var config = ConfigFile.new()
  var err = config.load(CONFIG_PATH)
  if err == OK:
    print("Game config loaded successfully.")
  else:
    push_error("Failed to parse config: error code %d" % err)

The fix is to open your export preset, go to the Resources tab, and add your custom extensions to the Filters to Export Non-Resource Files/Folders field. For example, enter *.cfg, *.json, *.dat to include all files with those extensions. You can also use path-based filters like data/* to include everything in a specific directory.

GDExtension Libraries Missing from Export

If your project uses GDExtension addons (native plugins compiled as shared libraries), the export process may not automatically include the platform-specific binaries. The .gdextension configuration file tells Godot where to find the libraries for each platform, but the export filter must still include those library files in the final build.

When a GDExtension library is missing from the exported build, the game crashes on startup when Godot tries to load the extension during initialization. The crash is typically immediate and produces minimal error output because the extension loading happens very early in the engine startup sequence.

# Verify GDExtension loading status
extends Node

func _ready():
  # List all loaded GDExtensions
  var extensions = GDExtensionManager.get_loaded_extensions()
  print("Loaded GDExtensions: ", extensions.size())
  for ext in extensions:
    print("  - ", ext)

  # Check a specific extension
  var status = GDExtensionManager.get_extension_status("res://addons/my_plugin/my_plugin.gdextension")
  match status:
    GDExtensionManager.LOAD_STATUS_OK:
      print("Extension loaded successfully")
    GDExtensionManager.LOAD_STATUS_FAILED:
      print("Extension FAILED to load - check library paths")
    GDExtensionManager.LOAD_STATUS_NOT_LOADED:
      print("Extension not loaded - file may be missing")

To fix this, add the native library extensions to your export preset’s non-resource file filters. Add *.dll for Windows, *.so for Linux, and *.dylib for macOS. Also verify that the .gdextension file itself is included. Some addon developers provide export plugin scripts that handle this automatically — check the addon’s documentation.

"The export works but the game crashes. That sentence has kept me up at night more times than I care to admit. Now I have a checklist: templates match, .pck is present, autoloads resolve, resources are included, extensions are bundled. Five checks, five minutes, zero mystery crashes."

Related Issues

If your exported game launches but shows a black screen instead of crashing, see our guide on HTML5/web export blank screens which covers rendering initialization failures. For exports that crash only on specific platforms, Android Gradle export errors and iOS code signing issues address platform-specific problems. If the export itself fails before producing a binary, export template version mismatches covers the pre-export validation step in detail.

Always test your export on a clean machine. Your dev box has files the export does not.