kxbuild: command not found / is not recognized as an internal or external command

The install script changed PATH, but your terminal or VS Code was opened before the install. Open a new terminal and restart VS Code. If that doesn't help, check that the bin folder of the install directory is on PATH. In the extension, you can click "Locate Installation…" in the KXBuild view to point to it.

The build can't find dependencies (Pods)

You built the .xcodeproj, but the dependencies live in the CocoaPods workspace. Run pod install first, then build the generated .xcworkspace. The same applies to React Native, Flutter and Cordova projects.

Swift packages won't download, or the build can't find a package

The dependencies haven't been resolved yet, or the cache is corrupted. Run kxbuild resolve . If that doesn't help, add --force to reset the caches.

Run Script phase fails (Flutter / React Native / Kotlin Multiplatform)

The framework's own tooling isn't ready. For example, FLUTTER_ROOT isn't set for the Flutter SDK, Node dependencies aren't installed, Kotlin/Native isn't patched, or JAVA_HOME isn't set. Run kxbuild doctor with the project path. It sets all of this up.

No signing certificate matching "…" found

The keychain folder has no certificate of the type the project asks for, or the team doesn't match. Add the matching .p12, or use -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=… to pick one that's already in the folder.

no provisioning profile named "…"

The project sets PROVISIONING_PROFILE_SPECIFIER, and the keychain folder has no profile with that name. Add a .mobileprovision with that name, or switch the project back to automatic signing, which matches profiles by bundle ID and team.

The build succeeds, but the app won't install or won't open

The app isn't signed, the provisioning profile doesn't include this iPhone's UDID, or an enterprise certificate isn't trusted on the iPhone. Check where your keychain folder is. Add the UDID to the development profile and download it again. For enterprise signing, trust the developer on the iPhone in Settings > General > VPN & Device Management.

kxdevice device list is empty and Windows can't see the iPhone

The Apple device drivers or service aren't running, the cable doesn't carry data, or the iPhone is locked or hasn't trusted the computer. Run KXBuild: Diagnose Devices or kxdevice doctor. Try another cable or port, unlock the iPhone and tap Trust. If Apple Devices can see the iPhone, so can KXBuild.

Can't connect to instruments or debugserver, or a Developer Mode message appears

Developer Mode is off, or the Developer Disk Image isn't mounted. On the iPhone, go to Settings > Privacy & Security > Developer Mode, turn it on and restart. Reconnect the iPhone and press F5 again.

Breakpoints don't hit, or stop in assembly

You built with the Release configuration, where optimization moves breakpoint locations, or the device symbols haven't finished downloading. Debug with the Debug configuration, and wait for the device symbols to finish downloading.

The app installs but shows a red screen on launch (React Native / Expo)

A network problem. The iPhone can't reach the Metro dev server on your computer. Put the iPhone and the computer on the same network, and allow the Metro port through Windows Firewall.

A Release build produces no .ipa

The build target isn't an app, or you passed --no-ipa. Pick the app's scheme with -s. Builds in other configurations write build\ - .ipa, and --ipa PATH sets a different path.

Upload fails with Invalid Bundle or missing SwiftSupport

You uploaded a zip you packed by hand, not the .ipa from the build. Upload build\ .ipa as is. It already has the structure App Store Connect requires.

Troubleshooting

Run kxbuild doctor first. Then look up your error message by category: install, project, signing, device, release or extension. Also covers where to find the logs.

Run doctor first

Most install, build and connection problems come from the environment. Run kxbuild doctor to check and fix the toolchain, SDK, CocoaPods, Node and device drivers. With a project path, it also sets up what Flutter, React Native, Expo or Kotlin Multiplatform projects need. In VS Code, run KXBuild: Doctor (fix environment).

> kxbuild doctor

> kxbuild doctor D:\projects\MyApp -v

-v prints every step and the full subprocess output. That output is the most useful thing to include when you ask for help. To update kxbuild, run kxbuild update, which runs doctor again afterwards. Leave off --json when troubleshooting, because error details appear only in the normal output.

Where to find logs

What	Where
Build log	The KXBuild channel in the VS Code Output panel, or the terminal for the CLI. Add -v to see every compile command.
Compile errors	The VS Code Problems panel. Click an error to jump to the source line.
Debugger output	The Debug Console.
Device logs	kxdevice syslog for the system log, kxdevice ostrace for os_log.
Crash reports	kxdevice crash
doctor details	kxbuild doctor -v

Find your error

Install and toolchain

kxbuild: command not found / is not recognized as an internal or external command: CauseThe install script changed PATH, but your terminal or VS Code was opened before the install.; FixOpen a new terminal and restart VS Code. If that doesn't help, check that the bin folder of the install directory is on PATH. In the extension, you can click "Locate Installation…" in the KXBuild view to point to it.

The Swift toolchain download stops partway: CauseAn unstable network. The toolchain is about 1 GB.; FixRun the same install command again. It resumes where it stopped.

doctor reports that the Swift SDK and toolchain versions don't match: CauseThe toolchain or SDK was swapped by hand.; FixLet doctor fix it. If they still don't match, run kxbuild update and then doctor again.

Path errors on Windows (file name too long, file not found): CauseLong path support is off, or the project is nested too deep.; Fixdoctor turns on long path support in Windows, which needs one admin approval. Keep projects in a short path such as D:\proj. This matters most for React Native projects and projects exported from Unity.

The extension reports a toolchain version mismatch or asks you to run doctor: CauseOnly one of the extension and kxbuild was updated.; FixRun doctor as prompted, or run kxbuild update and restart VS Code.

Projects and builds

The build reports an invalid path: CauseYou passed a directory to kxbuild build instead of a project file.; FixPass a path that ends in .xcodeproj or .xcworkspace. For a Swift package, pass the directory that contains Package.swift.

The build can't find dependencies (Pods): CauseYou built the .xcodeproj, but the dependencies live in the CocoaPods workspace.; FixRun pod install first, then build the generated .xcworkspace. The same applies to React Native, Flutter and Cordova projects.

Swift packages won't download, or the build can't find a package: CauseThe dependencies haven't been resolved yet, or the cache is corrupted.; FixRun kxbuild resolve <project>. If that doesn't help, add --force to reset the caches.

A Debug build fails to link with undefined symbol: …vpfi: CauseA known issue in the open-source Swift compiler when it compiles file by file. It happens with a property that has an initial value, such as @State private var count = 0, when the struct's init is in another file. Remote Swift packages are already built as a whole module by default, so the error comes from your own code or a local package.; FixSet the environment variable KXBUILD_SWIFT_WHOLE_MODULE=all, reopen your terminal or VS Code, and build again. Every Swift target is then built as a whole module. To try it for one build, add -D KXBUILD_SWIFT_WHOLE_MODULE=all. You can also move the init into the file that declares the property.

Metal shaders (.metal) … need metal, which is not installed on this host: CauseThe project has Metal shaders, and Apple's Metal compiler isn't installed on this machine.; FixSign in with your Apple Account, then download and install Metal Developer Tools for Windows. See Metal shaders.

scheme / target "…" not found: CauseThe name is wrong, or the scheme isn't shared.; FixRun kxbuild project info <project> to list every scheme and target. In projects exported from Unity, the target is called Unity-iPhone.

No templates to choose from when creating a project: CauseThe templates component isn't installed yet.; FixRun kxbuild doctor again.

Run Script phase fails (Flutter / RN / KMP): CauseThe framework's own tooling isn't ready. For example, FLUTTER_ROOT isn't set for the Flutter SDK, Node dependencies aren't installed, Kotlin/Native isn't patched, or JAVA_HOME isn't set.; FixRun kxbuild doctor <project dir> with the project path. It sets all of this up.

Code completion or go to definition doesn't work: Causecompile_commands.json is out of date, or Swift and clangd are both handling the same file type.; FixRun KXBuild: Generate compile_commands.json, then KXBuild: Restart Code Completion. If that doesn't help, run KXBuild: Re-Index Project. clangd handles .m, .mm, .c and .cpp files, and SourceKit-LSP handles Swift. Don't add the C-family languages back to SourceKit-LSP in settings.

Signing

No signing certificate matching "…" found: CauseThe keychain folder has no certificate of the type the project asks for, or the team doesn't match.; FixAdd the matching .p12, or use -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=… to pick one that's already in the folder.

no provisioning profile named "…": CauseThe project sets PROVISIONING_PROFILE_SPECIFIER, and the folder has no profile with that name.; FixAdd a .mobileprovision with that name, or switch the project back to automatic signing, which matches profiles by bundle ID and team.

The certificate can't be read, or the password is wrong: Causepassword.properties has no entry for this certificate, or the file name doesn't match.; FixAdd one line per certificate in the form name.p12=password. The file name includes the extension and is case-sensitive. Write the password as is, including any = signs or spaces, without quotes.

The build succeeds, but the app won't install or won't open: CauseThe app isn't signed, the provisioning profile doesn't include this iPhone's UDID, or an enterprise certificate isn't trusted on the iPhone.; FixCheck where your keychain folder is. See Certificates and signing. Add the UDID to the development profile and download it again. For enterprise signing, trust the developer on the iPhone in Settings > General > VPN & Device Management.

Devices and debugging

kxdevice device list is empty: CauseThe Apple device drivers or service aren't running, the cable doesn't carry data, or the iPhone is locked or hasn't trusted the computer.; FixRun KXBuild: Diagnose Devices or kxdevice doctor. Try another cable or port, unlock the iPhone and tap Trust. If Apple Devices can see the iPhone, so can KXBuild.

No devices in WSL: CauseWSL isn't going through the Windows-side relay, or usbipd is passing the iPhone through to WSL.; FixRun kxdevice doctor inside WSL, and don't use usbipd passthrough at the same time.

Can't connect to instruments or debugserver, or a Developer Mode message appears: CauseDeveloper Mode is off, or the Developer Disk Image isn't mounted.; FixOn the iPhone, go to Settings > Privacy & Security > Developer Mode, turn it on and restart. Reconnect the iPhone and press F5 again.

Breakpoints don't hit, or stop in assembly: CauseYou built with the Release configuration, where optimization moves breakpoint locations, or the device symbols haven't finished downloading.; FixDebug with the Debug configuration, and wait for the device symbols to finish downloading.

The app installs but shows a red screen on launch (RN / Expo): CauseA network problem. The iPhone can't reach the Metro dev server on your computer.; FixPut the iPhone and the computer on the same network, and allow the Metro port through Windows Firewall. See the React Native page.

Dart breakpoints don't work (Flutter): CauseThe Dart extension isn't installed.; FixInstall Dart-Code.dart-code and start debugging again.

Release

A Release build produces no .ipa: CauseThe build target isn't an app, or you passed --no-ipa.; FixPick the app's scheme with -s. Builds in other configurations write build\<App>-<Config>.ipa, and --ipa PATH sets a different path.

Upload fails with Invalid Bundle or missing SwiftSupport: CauseYou uploaded a zip you packed by hand, not the .ipa from the build.; FixUpload build\<App>.ipa as is. It already has the structure App Store Connect requires.

Extension

The KXBuild view says "No KXBuild installation was found on this machine": CauseThe toolchain isn't installed yet, or it's installed where the extension can't find it.; FixClick "Install KXBuild" or "Locate Installation…" in the view, then reload the window after the install. See Install the extension and toolchain.

The extension reports a version mismatch or asks you to run doctor: CauseOnly one of the extension and kxbuild was updated.; FixRun KXBuild: Doctor (fix environment), or run kxbuild update in a terminal. Update the extension itself from the Extensions view.

The Project Settings Editor is read-only and says "The project settings editor needs a newer kxbuild toolchain.": Causekxbuild is too old.; FixRun kxbuild update. If the editor is still read-only, update the extension to the latest version.

Still stuck?

Send the output of kxbuild version and kxbuild doctor -v, plus the full log of the failing command, through Contact us. A sample project helps most. If you can't share one, tell us the project type and iOS version.

Next steps

kxbuild command reference

Every kxbuild subcommand and option, including doctor, build, resolve, project, update and version.

Set up your device

Get your computer to recognize your iPhone. Install the driver, trust the computer and turn on Developer Mode, download device symbols before your first debug session, and choose between multiple devices.