When the Workflow Breaks: Errors, Logs, and Recovery
When iloader fails, the most useful first fact is not the wording of the final toast but the phase that stopped. This chapter shows how iloader connects a failed download, device operation, signing attempt, pairing transfer, or account action to a typed error, detailed evidence, and bounded recovery guidance. The reader's practical capability is to narrow the cause before changing state, treating suggestions as hypotheses to test rather than as automatic diagnoses.
Start with the phase that failed
An iloader operation is a chain of phases with different owners. A bundled installation can download a release asset, pass it to the sideloading library for signing and installation, discover the intended companion app, and place pairing material. Device selection has its own discovery and pairing work. Account management can contact developer services for certificates or App IDs. When an operation stops, the phase identifies the first boundary to investigate.
A download failure is evidence about the request for the release asset or the host's ability to reach it. It is not evidence that the selected device needs to be paired again. A device or lockdown error points toward usbmuxd, the phone, trust, or communication. A failure from the delegated signing path may involve account credentials, developer services, available resources, package requirements, or the device provider. A pairing-phase error can occur after the application is already installed, so downloading the same IPA again may not address the problem. The phase does not prove a cause, but it eliminates remedies that belong to unrelated phases.
iloader preserves this distinction in two layers. The native operation emits started, finished, and failed events for named steps, and the failure event carries an AppError. The frontend records which steps have started or completed and shows later steps as not started or skipped after a failure. For a bundled install, the user can see that downloading finished while installation failed, or that installation finished while pairing failed. For arbitrary IPA import, the visible operation has only an install step because iloader does not know a product-specific follow-up destination.
The error type adds a second filter. Rust defines categories for authentication, account lock, developer-service errors, anisette, download, usbmuxd, general device communication, lockdown pairing, remote pairing, House Arrest, storage, keyring, filesystem, certificate/app limits, cancellation, and missing prerequisites. The conversion code walks the underlying rootcause report and recognizes selected low-level cases. An Apple/isideload authentication code can become an account-locked or general-authentication error; a developer error can become an underage or general developer error; a socket failure can become device communication; a message about too many installed apps can become a maximum-apps error. Unrecognized reports fall back to a miscellaneous category.
This classification is useful because it turns a collection of library-specific failures into a stable interface. The frontend does not need to understand every error type emitted by every dependency. It can map a stable category to relevant suggestions while retaining the original message for inspection. The category is still an interpretation.