Troubleshooting

macOS will not open the app

Install from the disk image into Applications, then open it from there. On the first launch, if macOS says the app cannot be opened, Control-click ICCery and choose Open. You need macOS 12 Monterey or later.

If the disk image window has no background picture, you still have the app icon; drag that to Applications. (Current builds include a HiDPI background that shows on Monterey and later Finder.)

A numbered step stays dimmed

The sidebar looks at files in the working folder, not at what you remember doing.

To unlock	This file must exist for the current basename
Step 2	`.ti1`
Step 3	`.ti2` (and usually the matching `.ti1`)
Step 4	`.ti3`
Step 5	`.icc` or `.icm`

If a project file claims a later stage than the folder can support, the chip says Disk behind project notes. Trust the folder.

The printer from a recipe is not installed

The recipe remembers a print queue that this Mac does not have. Install that queue in System Settings, or pick another queue on step 2. Apply does not stop the session.

The print already looks colour managed

The driver is still adjusting colour. Set it to Off / No Color Adjustment / Application Managed and print the chart again. Do not measure the managed sheets.

Layout fails or no thumbnails appear

Read the banner. Typical causes: missing .ti1, a page size the layout tool rejected, or an instrument code the chart generator does not accept. Stay on step 2, fix the control, click Create Layout again.

The instrument list is empty

Allow the USB accessory prompt if macOS showed one.
Click refresh on step 3 or in Spot Read.
Try another cable and skip the hub.
Use step 3, not Spot Read, for an XY table's place-align-scan sequence.

Spot Read says the tool is missing

This copy of the app was packaged without measuring tools. Install a complete ICCery. Pointing Settings at some other folder only helps if that folder really contains the missing tool.

The gamut window shows a message instead of a shape

This Mac could not start the 3D view. Layer checkboxes, Add compare, and Inspect by typing Lab still work. Reset view will not create a graphics session. Close the window and continue profiling.

The default instrument is ignored on step 2

That is intended. Settings chooses the device you measure with. Step 2 chooses the device code printed on the chart. Set both. They are often the same device, but they are two menus.

Save on Settings reports an error about thresholds

Warning delta E must be strictly higher than Good delta E. Change one of the two fields and Save again.

Save Project stays off

There is no basename or no folder yet.
You are in Calibrate Printer under a temporary CAL_ name. Click Return to Profiling first.
A reading is still running. Stop or cancel it.

Help labels make the sidebar look crowded

Click the question mark to turn them off. They are extra labels, not a broken layout.

Verification is good but a photo print is wrong

The profile describes the chart. A photo print also depends on:

choosing this ICC in the print dialog
how the image editor handles colour
whether the driver is still managing colour
whether the paper in the tray is the paper you profiled

Fix the print path before you throw the profile away.

Where to look next

Settings > Logging > Copy excerpt for a short log. Attach that when you report a problem. Only send a .ti3 if you mean to share the measurements.

Contributor notes, build steps, and packaging live in the source README.