Diagnosing and Fixing Ren'Py Save‑Game Incompatibility Errors

Recognizing a Save Game Incompatibility

When the game starts, Ren'Py may print a message such as "Save game is incompatible with this version of the engine." or it may crash immediately after a jump from a loaded state. The symptoms usually include:

• Immediate crash or error stack trace after the game loads a previously saved file.
• Missing or corrupted variables when the game resumes.
• The “Force New Game” button appears in the main menu instead of the normal “Continue” option.

These symptoms indicate that the engine cannot reconcile the persisted data with the current script.

Common Causes

In Ren'Py, a save file is a pickled Python object that captures the entire game state. If the script changes in ways that the pickle cannot interpret, the load fails. Typical triggers include:

• Renaming or removing a label that is a target of a jump or call in an existing save.
• Changing the type or default value of a variable that was previously defined.
• Adding a new variable without providing a default value.
• Moving the config.save_directory path, causing the engine to look for saves in the wrong location.
• Manually editing the .save file, which corrupts the pickle structure.

Diagnostic Table

Possible Cause	Check	Fix
Label renamed or deleted	Open the script and verify that every jump or call target still exists.	Restore the old label name, or add a label old_name: that redirects to the new one using jump new_name.
Variable changed type or missing default	Search for define statements that were altered or removed.	Re‑add the variable with a default assignment or provide a migration script that sets a fallback value.
New variable without default	Look for define or default statements added after the last save.	Wrap the new variable in default so it is persisted, or add a default block that initializes it.
Save directory changed	Check config.save_directory in the script.	Set it back to the original path or move the existing .save files into the new directory.
Corrupted .save file	Attempt to load the file; if it fails with a pickle error, the file is corrupted.	Delete or rename the file and start a new game; keep a backup if you need to preserve progress.

Step‑by‑Step Troubleshooting

1. Reproduce the error. Create a new save, then modify the script (e.g., rename a label) and try to load the save again. This confirms the incompatibility.
2. Inspect the error message. The stack trace often points to the exact line where the load fails. Note any NameError or AttributeError references.
3. Validate script integrity. Open the script in a text editor and search for the labels and variables mentioned in the error. Verify that they exist and are defined correctly.
4. Check config.save_directory. If you changed this setting, ensure the directory exists and contains the .save files.
5. Run a migration helper. If you added new variables, add a default block that sets them to a safe value. Example:

   default new_var = None
   

   This ensures the variable is present in all future saves.
6. Test the fix. Reload the game. If the save loads successfully, the issue is resolved.
7. Backup before major changes. Keep a copy of the .rpy files and the .save directory in version control or an external backup.

Fixes and Mitigations

• Use default for persistent variables. Unlike define, default guarantees that the variable is stored in the save file and can be updated when the script changes.
• Provide migration scripts. When you must rename a label, add a temporary label that redirects to the new name. Example:

  label old_start:
      jump new_start
  

  This keeps old saves functional.
• Keep a consistent save directory. If you need to move config.save_directory, copy the entire .save folder to the new location.
• Avoid manual edits. The .save files are binary pickles. Editing them with a text editor will corrupt them.
• Use renpy.game.restart() when state is irrecoverable. This function clears the current state and starts the game fresh. It is typically invoked by the engine when it detects a fatal incompatibility. If you encounter a persistent crash, you can call it manually in a screen or label.

  label start:
      if not renpy.is_loaded():
          renpy.game.restart()
  

When to Escalate

If the above steps do not resolve the issue, consider:

• Checking the Ren'Py changelog for any breaking changes that might affect your script.
• Posting a minimal reproducible example on the Ren'Py forums or Discord. Include the error message, the relevant script snippet, and the version of Ren'Py you are using.
• Consulting the renpy.log file for deeper diagnostics.

Quick Reference Checklist

• Did you rename or delete any labels used by existing saves?
• Are all persistent variables declared with default?
• Has config.save_directory changed?
• Did you accidentally edit a .save file?
• Is your Ren'Py engine up‑to‑date with the script?

Answering “yes” to any of these questions likely points to the root cause of the incompatibility.