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_DATALESSbefore reading a.uprojectduring 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::FindProjectsandFProjectDescriptor::Loadon 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 Projectsis 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
- Turn on iCloud Drive “Desktop & Documents Folders” sync.
- Have any project in
~/Documents/Unreal Projects/<Name>/. - 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 showcompressed,dataless. - 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.
- Launch the editor with any project, for example by double-clicking a different
.uprojectstored 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