Fix: Black Screen When Launching iOS Simulator from Xcode

Fix: Black Screen When Launching iOS Simulator from Xcode

Written by

in

Quick answer: To fix a black screen in iOS Simulator when Xcode hangs on launch, open Simulator and select Device > Erase All Content and Settings…, or run xcrun simctl erase all in Terminal. If the issue happens in a new or edited project, also verify that your target’s Main Interface setting points to a valid storyboard or that your root window is initialized in code.

Why this happens

When you click Run in Xcode and the iOS Simulator opens to a black screen with only the status bar visible, the problem usually comes down to one of two issues: a broken debug connection between Xcode and the simulator, or a missing initial interface in your app target.

In the first case, Xcode compiles the app and installs it on the simulator, but CoreSimulatorService or LLDB hangs before the app process finishes launching under the debugger. Because the app bundle is already installed, pressing the Home button in Simulator and tapping the app icon often launches it normally. Meanwhile, Xcode still believes the debug session is active, which is why clicking Stop or trying to quit Xcode causes it to hang.

In the second case, UIKit launches your app process, but no root view controller is loaded. If Main Interface is blank or points to a deleted storyboard—or if programmatic window setup is missing—the app renders an empty UIWindow, leaving a black screen behind the status bar.

How to fix it

1. Erase All Content and Settings in Simulator

Resetting the simulated device clears corrupted app containers, stale launchd_sim state, and stuck debugger hooks. This resolves most cases where every new project fails with the same black screen.

  1. Stop the running task in Xcode (Command + .). If Xcode is frozen and refuses to stop the task, force quit Xcode (Command + Option + Escape).
  2. Open Simulator.
  3. From the macOS menu bar, choose Device > Erase All Content and Settings…
  4. Click Erase to confirm and wait for the simulator to boot back to the Home Screen.
  5. Reopen your project in Xcode and press Command + R to build and run.

If you prefer Terminal, or if Simulator itself is unresponsive, shut down and erase all simulators with simctl:

xcrun simctl shutdown all
xcrun simctl erase all

2. Verify Main Interface and window setup

Before wiping simulator data, confirm that your project actually tells iOS what UI to load on launch.

  1. In Xcode, select your project at the top of the Project navigator.
  2. Select your app under Targets and open the General tab.
  3. Under Deployment Info, check the Main Interface field. If your project uses a storyboard, make sure it matches the storyboard filename (for example, Main).

If you intentionally deleted Main.storyboard to build your interface in code, clear Main Interface and remove any leftover storyboard references in Info.plist (such as Main storyboard file base name or the storyboard entry inside Application Scene Manifest). Then make sure your SceneDelegate creates and activates a UIWindow:

import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        guard let windowScene = scene as? UIWindowScene else { return }
        let window = UIWindow(windowScene: windowScene)
        window.rootViewController = ViewController()
        window.makeKeyAndVisible()
        self.window = window
    }
}

If you are using SwiftUI, check that your @main App struct returns a WindowGroup containing your root view.

3. Restart CoreSimulatorService when Xcode hangs

When Xcode refuses to quit and displays a prompt waiting to stop tasks, restarting the background simulator service clears the deadlock without requiring a full Mac reboot.

  1. Force quit Xcode and Simulator.
  2. Open Terminal and terminate the CoreSimulator daemon:
killall -9 com.apple.CoreSimulator.CoreSimulatorService
  1. Reopen Xcode, select a simulator destination, and run your app again. macOS automatically restarts CoreSimulatorService when Xcode requests a simulator.

4. Clean the build folder and DerivedData

Stale build products or a mismatched app bundle in DerivedData can also cause the debugger to stall during launch.

  1. In Xcode, choose Product > Clean Build Folder (Shift + Command + K).
  2. Delete the app from the simulator Home Screen if it is already installed.
  3. If the problem affects multiple projects, clear DerivedData from Terminal:
rm -rf ~/Library/Developer/Xcode/DerivedData/*
  1. Build and run again (Command + R).

How to prevent it

  • Stop active runs in Xcode (Command + .) before quitting Simulator or switching Git branches.
  • Avoid running several simulator devices simultaneously when system memory is low.
  • Keep Main Interface and Info.plist scene keys in sync whenever you rename or remove a storyboard.
  • Run xcrun simctl shutdown all after updating Xcode so older simulator sessions do not stay active in the background.

FAQ

Why does the app open when I tap its icon on the Simulator Home Screen?

Xcode successfully compiled and installed the app bundle onto the simulator, but the debugger handshake stalled before UIKit could present the first screen. Launching the app directly from the Home Screen bypasses Xcode’s debugger attach step, so the app opens normally.

Will “Erase All Content and Settings” delete my Xcode project or source code?

No. Erase All Content and Settings… only wipes the virtual device’s storage, installed test apps, and cached preferences inside the simulator. Your Xcode project files and source code on disk remain untouched.

Why does Xcode hang when I try to quit or stop the simulator task?

Xcode waits for CoreSimulatorService and LLDB to confirm that the running simulator process has terminated. When that communication channel is deadlocked, Xcode cannot complete the stop request until you force quit Xcode or kill com.apple.CoreSimulator.CoreSimulatorService.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 3.0; this article is shared under the same license.