Editor hangs on startup (no window) when a .uproject in the default projects folder is an iCloud "dataless" placeholder

Summary

On macOS, the editor hangs forever during startup, before any window appears, if any .uproject file under the default projects folder (~/Documents/Unreal Projects/) has been offloaded by iCloud Drive (marked dataless) and iCloud doesn’t deliver the file.

Building the Home Screen’s embedded Project Browser reads every .uproject there synchronously on the GameThread, with no timeout. If iCloud stalls, that read() never returns. The editor shows no window and no error, stops logging, and doesn’t respond to a normal quit (it needed SIGKILL).

The hang also happens when launching a different project. In my case I opened project A, and the editor hung on project B, which I never asked to open.

Environment

  • Engine: 5.9.0-60351404+++UE5+Release-5.9 (Launcher build)
  • OS: macOS 27.0.1 (26A434)
  • Hardware: Apple M6
  • iCloud Drive with “Desktop & Documents Folders” turned on (a common macOS setup)

Evidence

The last meaningful log lines, after which there’s only periodic unrelated noise:

LogProjectBrowser: Looking for projects...
LogProjectBrowser: Found Engine Installation "{F0246C2F-...}"(/Volumes/.../UE_5.9)
LogProjectBrowser: Enumerating Launcher Sample Projects...

The log’s frame counter stays at [ 0] for the whole hang.

GameThread stack (sample <pid>), every sample in the same place:

GuardedMain
 EditorInit(IEngineLoop&)
  FMainFrameModule::CreateDefaultMainFrameAuxiliary
   FTabManager::RestoreFrom / RestoreArea / RestoreArea_Helper
    FTabManager::SpawnTab
     FMainFrameModule::SpawnHomeScreenWindow
      HomeScreenHelper::GetHomeScreenSettings
       HomeScreenHelper::GetRecentProjectListWidget
        FGameProjectGenerationModule::CreateEmbeddedProjectBrowser
         SProjectBrowser::Construct
          SProjectBrowser::FindProjects
           FProjectManager::QueryStatusForProject
            FProjectDescriptor::Load
             FFileHelper::LoadFileToString
              FFileHandleApple::ReadInternal
               read   <-- blocked

lsof on the editor process shows the open file descriptor is the dataless .uproject:

25r REG ... ~/Documents/Unreal Projects/Alize/Alize.uproject   (flags: compressed,dataless)

Workaround

Move the offloaded project out of ~/Documents/Unreal Projects/, or right-click it → Keep Downloaded. Then force-quit and relaunch the editor.

Suggested fixes

  • Skip offloaded files without reading them. Check stat().st_flags & SF_DATALESS before reading a .uproject during project discovery. This check doesn’t trigger a download. Show those projects as “Not downloaded” or skip them.
  • Move project discovery off the GameThread. Run SProjectBrowser::FindProjects and FProjectDescriptor::Load on a background thread and fill in the list as results arrive, so one slow file system can’t block the editor from starting.
  • Optionally, warn about the default location. Point out that ~/Documents/Unreal Projects is iCloud-synced when Desktop & Documents sync is on. That syncing also causes unwanted upload of DerivedDataCache, Intermediate and Saved folders.

What Type of Bug are you experiencing?

AI

Steps to Reproduce

  1. Turn on iCloud Drive “Desktop & Documents Folders” sync.
  2. Have any project in ~/Documents/Unreal Projects/<Name>/.
  3. Offload it: in Finder, right-click the folder → Remove Download (or let macOS offload it to save space). Confirm with ls -lO <Name>.uproject, which should show compressed,dataless.
  4. Make iCloud fail to deliver the file, for example by going offline or by iCloud stalling on its own, which is what happened in my case.
  5. Launch the editor with any project, for example by double-clicking a different .uproject stored elsewhere.

Expected Result

The editor starts. The offloaded project is skipped or shown as unavailable or “in iCloud”.

Observed Result

The editor process runs at near-zero CPU but never shows a window. In my case it stayed that way for over an hour.

Affects Versions

5.9

Platform(s)

Mac