Docs / Virtual iOS device / Troubleshooting

Virtual iOS device: troubleshooting#

Symptom, cause, fix. Error codes and messages are the ones Tomacco really prints. For the rest of the product, see the general troubleshooting guide.

Start here. These say what state you are in:

tomaccoctl call ios.virtual.doctor '{}'
python3 tools/ios_virtual_profile.py --check
tomaccoctl call ios.virtual.status '{}'

ios.virtual.doctor is one pass, warn or fail report with a remedy per item: the profile's inputs (as ios_virtual_profile.py --check checks a new profile's), whether the guest tools and the engine were built from this checkout's sources, the saved states' disks, the last run's verdict, whether the next start's disk copy fits, every ios.virtual.host_check item, and the graphics card and host pressure right now. It reads files only. Its checks are unit-tested with profiles made in the tests; it has not been run against a full live profile yet.

To read why a start failed, use the job from busy or from the start's own answer:

tomaccoctl call job.logs '{"job_id":"START_JOB","offset":0}'

Error codes#

Every error code of the virtual iOS device that tomaccoctl returns, in alphabetical order. The code is the error.code of the JSON answer; its message and remedy say more. A test checks that each code here exists in the code and that none is missing.

Setup#

Starting#

An app does not open#

Reading the guest's own view, with GUEST_JOB being guest_job from ios.virtual.status:

tomaccoctl call ios.emulator.guest '{"job_id":"GUEST_JOB","operation":"logs","argument":"development"}'
tomaccoctl call ios.emulator.guest '{"job_id":"GUEST_JOB","operation":"crash_reports","argument":"MyApp"}'

To keep an app's reports as files on the host, for example for ios.crash_symbolicate:

tomaccoctl call ios.virtual.crash_reports '{"process":"MyApp","directory":"/absolute/crashes"}'
tomaccoctl call ios.crash_symbolicate '{"report":"/absolute/crashes/mobile/MyApp-2026-10-31-120000.ips","binaries":["/absolute/MyApp.app/MyApp"]}'

Each report lands in mobile/ or root/ under the directory, after the CrashReporter directory it came from, and the reply lists its path, sha256 and the pid and capture_time read from it. The guest hands over at most three reports per directory and 512 KiB in all, so collection_complete:false means some were left out, and an empty list does not prove that nothing crashed. iOS names some reports with their kind before the process, such as ExcUserFault_chronod-<date>.ips; pass the kind as process to get them. On a live phone this saved three such reports in 0.1 s with their PID, process and capture time. testing.crashes lists a report of that form under unparsed as not-a-crash: it records a fault the process lived through.

logs development shows the adapter's active line with entries, and an entry line per further identifier. That tells an inactive signing library from a refused bundle.

The phone's console log, where the kernel prints and launchd forwards log records, comes as structured lines with ios.virtual.syslog, filtered by process, level or text:

tomaccoctl call ios.virtual.syslog '{"process":"MyApp"}'
tomaccoctl call ios.virtual.syslog '{"levels":["error","fault"],"max_lines":100}'
tomaccoctl call ios.virtual.syslog '{"process":"MyApp","offset":123456}'
tomaccoctl call ios.virtual.syslog '{"bundle_id":"dev.example.MyApp","offset":123456}'

bundle_id keeps one app's lines: those its process writes under its executable's name (read from the bundle the profile lists, named in the reply's app) and launchd's lines about its service, such as exited due to SIGABRT. It matches names, not a PID, so following it with offset keeps the app's lines after a relaunch or a redeploy. An app the profile does not list is refused with ios_virtual_application_unknown.

Each line has time, process, pid, service, sender, level and message; a line of no known form is the kernel's. Without offset it reads the last 256 KiB; pass the reply's next_offset back to follow the log. It reads the guest job's uart.log on the host and asks the guest nothing, so it also works after the phone stopped, for the last run.

What a live phone's console holds: in one run's log (1.2 MiB, 9,283 lines from boot to stop) 8,238 lines were launchd's records, 1,043 the kernel's and 2 dyld's. No app's own log records reached the console, so process finds launchd's records about the app's service, such as when it was spawned and why it exited, not what the app logs itself. launchd names a service with its domain (user/501/SERVICE [PID]); an app's service is UIKitApplication:BUNDLE_ID[…], listed under the last part of its bundle identifier, and pid/PID [NAME] is the process NAME. A record about a whole domain, such as system or user/501, is launchd's own. A record that a kernel print cut in two stays the kernel's line.

While it runs#

Settings icons. icon_cache clear moves iOS's icon store aside (nothing is deleted) and restarts SpringBoard, which leaves the phone on its lock screen. Clear it once per boot; rendering every icon again takes minutes under emulation.

tomaccoctl call ios.emulator.guest '{"job_id":"GUEST_JOB","operation":"icon_cache","argument":"clear","timeout_seconds":120}'
tomaccoctl call ios.virtual.unlock '{}'

A Settings that was already running keeps the icons it holds. On a live phone it still showed the "?" squares 11 minutes after the clear; after a verified stop and a new start, the fresh Settings showed grey squares at first and every icon about 2 minutes later. The Home screen's app icons are rendered again too and may differ from the old ones in single pixels. The start does not clear the store by itself: it cannot see the "?" without opening Settings and judging its pixels, and a clear on every start would cost a SpringBoard restart and minutes of rendering.

Stopping#

Why was my run not verified? last_run in ios.virtual.status answers for the last run that finished:

{"verified": false, "outcome": "emulator-exited",
 "summary": "The emulator exited on its own with exit code 0.",
 "reasons": ["No stop asked the guest to flush its storage first: it ended on its own or was ended by force."],
 "remedy": "Stop the phone with ios.virtual.stop while it answers; a stop that has to end an unanswering guest cannot save it. The next start uses the last verified run."}

outcome is the launcher's classification of the run (for example kernel-panic, guest-process-crash or host-pressure-blocked), and summary says it in words. A run can be verified and still name a problem: a crash of an iOS process the emulator is not known to cause, or the graphics memory guard, is listed while the saved disks stay usable. The wording is unit-tested against recorded launcher records, not yet read off a live phone.

Still stuck#

ios.emulator.report with the guest job shows the emulator's outcome, and userspace_failures and respawn_storms list what went wrong inside iOS. An entry of kind guard-ended is expected. If you are still stuck, please open an issue with the report.

tomaccoctl report writes one archive for that issue, on this computer only. Its virtual-ios.json holds this machine's readiness from ios.virtual.host_check, the profile's run settings, ios.virtual.status, which engine and guest-tools builds the profile uses, and how the last guest run ended (its outcome, evidence counts, and the first userspace failures and respawn storms); virtual-ios/guest.log is the end of that run's log. Recognised secrets are masked and your home directory is shown as ~, but read the files before you share them. The archive holds no images, disks or other files of Apple's.

View this page as Markdown on GitHub