Project Upgrade tool leaves unclear backup state after unexpected termination

When the Project Upgrade tool is terminated unexpectedly, the backup state is considered unreliable. Because these tools typically perform a sequential file copy operation rather than an atomic snapshot, a forced termination often results in a partial or corrupted backup directory.

Backup Scope and Consistency

In standard configurations, the tool targets source-critical data to minimize backup time. The following directories are generally guaranteed to be present if the backup phase completed:

• Content/: All assets, meshes, and textures.
• Source/: C++ or C# source code.
• Config/: Project settings, input maps, and editor preferences.
• Plugins/: Local project-specific plugins (if not using a global plugin system).

However, engine-generated folders are typically excluded from the backup because they are transient. If the tool was killed during the copy process itself, the backup folder may contain an incomplete set of the above directories, making a simple restore insufficient without manual verification.

Restoration and Cleanup Steps\n

Restoring a backup after a crash requires active manual cleanup to ensure the engine does not attempt to load metadata from the failed upgrade. Follow these steps:

1. Close the engine and all project-related IDEs.
2. Manually delete the Intermediate/, Saved/, and Build/Binaries/ directories. These contain partially processed shaders and cached binaries from the failed upgrade.
3. Copy the contents of the backup folder back to the project root.
4. Launch the engine to trigger a full regeneration of the intermediate folders and a re-import of derived assets.

Handling Partially Processed Assets

Engine-generated assets (such as compiled shaders, derived data, or intermediate transform caches) that were partially processed during the failure are not safely omitted by the backup. Since they are derived from the source files, they must be cleaned up manually by deleting the cache-related folders mentioned above. Failing to do so can lead to "ghost errors" where the engine expects a version-specific bytecode that no longer matches the restored source files.

Note: To provide specific directory paths, please specify if you are using Unreal Engine, Unity, or a custom-built engine-based upgrade tool.