Troubleshooting
The errors you're most likely to hit, what each one means, and how to fix it.
Start with sochi doctor. It checks Xcode, Swift, devices, teams and simulators, and marks anything wrong with ✗.
sochi prints its own errors as a single line starting with ✗, and exits with status 1.
Finding the project
Section titled “Finding the project”No .xcodeproj or .xcworkspace found
Section titled “No .xcodeproj or .xcworkspace found”Run sochi from the folder that contains the project, or pass its path: sochi run ~/Code/Weather.
Found several projects (…). Pass one explicitly
Section titled “Found several projects (…). Pass one explicitly”The folder has more than one workspace, or more than one project. Pass the one you want: sochi run Weather.xcworkspace.
… is a Swift package. Only Xcode projects and workspaces are supported for now.
Section titled “… is a Swift package. Only Xcode projects and workspaces are supported for now.”sochi works with apps in an Xcode project or workspace. A folder with only a Package.swift isn’t supported yet.
No scheme named 'X'
Section titled “No scheme named 'X'”The message lists the schemes that exist. Check the spelling, or leave out --scheme to let sochi choose.
Scheme 'X' doesn't build an application
Section titled “Scheme 'X' doesn't build an application”run needs a scheme that builds an app. Pick the app’s scheme with --scheme.
Devices
Section titled “Devices”No device connected
Section titled “No device connected”Plug in and unlock your iPhone or iPad, or run on a simulator with --sim. sochi devices shows what’s paired and what’s reachable.
'x' matches N devices
Section titled “'x' matches N devices”Several devices match what you passed to --device. Type more of the name, or the start of the UDID.
No device or simulator matches 'x'
Section titled “No device or simulator matches 'x'”Check the name with sochi devices or sochi sims. For simulators, the name has to match exactly.
… didn't answer
Section titled “… didn't answer”The device was locked or asleep when the build tried to reach it. Unlock it and keep it awake, or connect it with a cable, then run again.
developer mode off in sochi devices
Section titled “developer mode off in sochi devices”Turn on Developer Mode in Settings › Privacy & Security on the device, then restart it.
No available iOS simulators
Section titled “No available iOS simulators”Install an iOS runtime in Xcode › Settings › Components.
Signing
Section titled “Signing”The project has no development team and no accounts are signed into Xcode
Section titled “The project has no development team and no accounts are signed into Xcode”Sign in under Xcode › Settings › Accounts, then run again.
The project has no development team. Choose one with --team or SOCHI_TEAM
Section titled “The project has no development team. Choose one with --team or SOCHI_TEAM”You have several teams and the project doesn’t name one. Pass one: sochi run --team A1B2C3D4E5. sochi remembers it.
Capabilities that need Apple’s approval
Section titled “Capabilities that need Apple’s approval”Some capabilities, marked (needs Apple approval) in sochi capabilities --all, only work once Apple has enabled them for your account. Signing fails until then.
Building
Section titled “Building”Another build of this project is running (sochi, Xcode or xcodebuild)
Section titled “Another build of this project is running (sochi, Xcode or xcodebuild)”Two builds can’t share the build database at once. Let the other one finish, then run again.
Refusing to install: …
Section titled “Refusing to install: …”The built app’s bundle ID or platform doesn’t match what sochi expected. Try --fresh. If it keeps happening, report it as a sochi bug.
The app runs an old build
Section titled “The app runs an old build”sochi skips installing when the device already has an identical build. Pass --fresh to reinstall anyway.
Editing the project
Section titled “Editing the project”This project looks generated (found project.yml)
Section titled “This project looks generated (found project.yml)”The project comes from XcodeGen or Tuist, so the next generation would undo sochi’s edit. Change the generator’s manifest instead, or pass --force.
This project uses the pre-Xcode 16 format
Section titled “This project uses the pre-Xcode 16 format”Adding targets needs a folder-based project. Run sochi migrate first.
Several targets could be meant
Section titled “Several targets could be meant”The project has more than one app target. Pick one with --target.
Edit didn't verify (…). No files were changed.
Section titled “Edit didn't verify (…). No files were changed.”sochi wrote the edit, but the project didn’t read back the way it should have, so sochi restored every file. The message says which check failed.
X needs a value for key
Section titled “X needs a value for key”The capability needs a value, such as a domain or an identifier. Pass it after the name. The message shows the expected format.
Packages
Section titled “Packages”sochi.toml and the project disagree
Section titled “sochi.toml and the project disagree”The same package changed in both sochi.toml and Xcode since the last sync. Edit one to match the other, then run sochi sync. See Keeping both sides in step.
Resolving packages failed; nothing was changed.
Section titled “Resolving packages failed; nothing was changed.”xcodebuild couldn’t resolve the packages. Check the URL, the version rule and your network connection. The message includes xcodebuild’s own errors.
X has no release tags
Section titled “X has no release tags”The repository has no version tags like 1.2.3. Use --branch or --revision instead.
Migrating
Section titled “Migrating”The converted project wouldn't build the same, so nothing was changed
Section titled “The converted project wouldn't build the same, so nothing was changed”The before and after builds compiled different sources or bundled different files. The list shows what differs. Usually a group needs fixing in Xcode first.
The project doesn't build as it is
Section titled “The project doesn't build as it is”sochi can’t compare builds of a project that doesn’t build. Fix the build, or pass --no-verify.
Still stuck
Section titled “Still stuck”Run the same build with xcodebuild to see Xcode’s raw output, or open an issue with the command you ran and what sochi printed.