MBProgressHUD usually works on the first try, but when it does not, the error can look confusing. A HUD that never appears, a build that fails, a spinner that freezes, or a crash when you show the HUD all have common causes, and most of them have quick fixes. This guide walks through the problems developers hit most often, in the order you are likely to hit them: install problems, import problems, threading problems, and display problems. Work through the list, change one thing at a time, and test after each fix.
Before you start, note the basics. What is your iOS deployment target, and which version of MBProgressHUD are you running? The latest stable version is 1.2.0, released in January 2020, and it requires iOS 9.0 or later with ARC. If you run a different version, update to 1.2.0 from the official repository. Also confirm which install method you used, because the fix depends on whether you used Swift Package Manager, CocoaPods, Carthage, or the source files directly.
The Build Fails: No Such Module
The most common build error in Swift is “no such module MBProgressHUD”. It means Xcode cannot find the library. If you installed it with Swift Package Manager, check that the library is linked to your app target. Select your project, go to your app target, open the “Frameworks, Libraries, and Embedded Content” section, and confirm MBProgressHUD is listed. If it is missing, add it there.
If you installed it with CocoaPods, the same error usually means you opened the .xcodeproj file instead of the .xcworkspace file, or you forgot use_frameworks! in your Podfile. Add use_frameworks! to the Podfile, run pod install again, open the workspace file, and build again. If you use a bridging header, do not write import MBProgressHUD in your Swift files, because the bridging header already exposes the class. Mixing both approaches causes the same error.
The Build Fails: File Not Found
The second most common build error is “file not found” for the MBProgressHUD header. That usually means you used the wrong import style. If you added the source files directly to your project, use quotes: #import “MBProgressHUD.h”. If you installed it as a framework through CocoaPods or Carthage, use angle brackets: #import <MBProgressHUD/MBProgressHUD.h>. Quotes mean the header is a file in your project. Angle brackets mean the header comes from a framework. If you use the wrong one, the build will fail.
Another cause is a deployment target mismatch. If your project targets an iOS version older than 9.0, the library will not build. Open your project settings, check the deployment target, and raise it to 9.0 or higher. Every modern app already targets a much newer version, so this problem is rare, but it is worth checking.
The HUD Never Appears
If the project builds but the HUD never appears on screen, check the view you added it to. The most common mistake is adding the HUD to a UITableView or a UICollectionView. Those views change their subviews in unexpected ways and can break the HUD display. Add the HUD to a plain view or to the window instead. In Swift, write MBProgressHUD.showAdded(to: self.view, animated: true) for a plain view, or use the window if you need it above everything.
Another cause is a grace time that is too long. If you set graceTime to a large value, such as 5 seconds, and your task finishes in 2 seconds, the HUD will never appear, because the task ends before the delay runs out. Check your graceTime setting and lower it to 0.5 seconds or less. A grace time is meant to hide the HUD for very fast tasks, not for normal ones.
The HUD Freezes or the App Crashes
If the HUD appears but the spinner does not animate, or the app crashes when you show or hide it, the problem is almost always threading. All show and hide operations must run on the main thread. If you call showAdded from a background thread, the HUD may not draw, or the app may crash. The same is true for hide.
Fix it by wrapping the show and hide calls in a main thread dispatch. In Swift, write DispatchQueue.main.async { MBProgressHUD.showAdded(to: self.view, animated: true) }. In Objective-C, write dispatch_async(dispatch_get_main_queue(), ^{ [MBProgressHUD showHUDAddedTo:self.view animated:YES]; }). Run the slow work on a background queue, and come back to the main thread to hide the HUD. A few setters are thread-safe from background threads, such as setMode and setProgress, but show and hide are not.
The Progress Bar Never Moves
If you show a determinate progress bar and it stays at zero, check that you are updating hud.progress. The value must move from 0.0 to 1.0 as the task runs. If you set the mode to determinate but never update the progress value, the bar will stay empty. Update it as your task reports progress, or connect an NSProgress object with hud.progressObject and let the HUD update itself.
If you update the progress value but the bar still does not move, check that you are updating the right HUD object. If you create a new HUD each time you update, the old one stays on screen and the new one is hidden. Keep a reference to the HUD you showed, and update that same object.
Clean the Build When Nothing Else Works
If you have checked the install, the import, the threading, and the view, and the problem is still there, clean the build. Xcode keeps cached files that can go stale, especially after you change a package, a pod, or a bridging header. Open the Product menu, hold the Option key, and choose Clean Build Folder. Then build again. That step fixes a surprising number of strange errors, and it costs only a minute.
If a clean build does not help, delete the derived data folder. You can find its location in Xcode settings, under Locations. Close the project, delete the folder, reopen the project, and build again. For a CocoaPods project, you can also delete the Pods folder and the Podfile.lock file, then run pod install fresh. That rebuilds the whole dependency setup from scratch, and it fixes most broken states that a clean build cannot.
Here is a quick troubleshooting order to follow:
- Confirm the library is linked to your app target and you opened the right project file
- Confirm you used quotes for source files and angle brackets for a framework
- Confirm you show and hide the HUD only on the main thread
- Confirm you added the HUD to a plain view or window, not a table or collection view
- Confirm you update the progress value for determinate modes
- Confirm your grace time is short and your deployment target is iOS 9.0 or later
Conclusion
Most MBProgressHUD problems fall into a few clear groups: a missing module or header at build time, a HUD that never appears because of the wrong view or a long grace time, a frozen spinner or crash because show and hide ran off the main thread, and a progress bar that never moves because the progress value was never updated. Work through them in order, change one thing at a time, and test after each fix. Check the install method first, then the import style, then the threading, then the view. Once the HUD appears, animates, and hides correctly, you are back to the real work, which is building an app that keeps the user informed while it works.
Read next: How to Install MBProgressHUD with CocoaPods, MBProgressHUD in Swift: Bridging Header Guide, MBProgressHUD vs SwiftUI ProgressView: Which Fits Your App?
