Troubleshooting

Shotlist’s messages are meant to name the fix. This page lists them by stage, with what each means and what to do. Messages are shown as Shotlist prints them; … stands for a path, a name or a number that varies.

Where to look

Source	What it holds
The command’s own output	The summary, every failure and its reason.
Shotlist/Output/run.log	The last capture, line by line, with warnings and errors. Times are UTC. Failed commands are quoted exactly, so you can run them yourself.
Shotlist/Output/manifest.json	Each cell’s state, and the error for every failed cell.
Shotlist/Output/previous/raw/	The previous run’s captures, to compare with raw/.
The Mac app’s Matrix	Select a cell for its full reason; Run Log shows the log live.
shotlist doctor	The state of Xcode, runtimes, disk, simulators and Duo automation.
Console.app	The engine also logs to the unified log, subsystem app.shotlist.engine: log stream --predicate 'subsystem == "app.shotlist.engine"'.

Common problems

Problem	Fix
Every cell fails waiting for a hello from the app	The host isn’t installed, or the app wasn’t built with DEBUG. See Setting up a project.
A scene is “not ready after 20 s”	The message names the open hold or pending URL. Add the fixture, release the hold, or make the waitUntil condition read observable state.
“the screen kept changing”	Something animates for ever: a spinner, a loop, a live time. A spinner usually means a missing fixture. Otherwise stop the animation when Shotlist.isActive.
A locale comes out in English	The app doesn’t declare that language. Add it to a String Catalog or an .lproj. verify reports this.
Cells change between runs with nothing changed	Usually an unpinned date, a missing timeZone, or an unstable sort. See Making runs identical.
The status bar shows “09:41”	Shouldn’t happen: each Shotlist simulator’s region is set to en_US once. If the log warns that the region is still something else, erase that simulator (xcrun simctl erase <udid>) and capture again.
A simulator quit or crashed mid-run	The cell it was on fails; Shotlist boots it again and carries on. Capture the failed cells again with --slots, --locales and --scenes.
All simulators shut down at once	Device Hub was quit. That shuts down every booted simulator. Don’t quit it during a run.
iPhone Duo inner cells fail	Unlock the Mac, grant Accessibility, and run shotlist capture --slots iphone-duo-inner. See iPhone Duo.
A caption overflows	Shorten it for that locale, or add a line break. See Text fitting.
verify refuses machine drafts	Have someone check them, then shotlist captions review --locales <locale>.
A setting in shotlist.json has no effect	Shotlist ignores keys it doesn’t know. Check the spelling against Configuration.

Configuration

Message	Meaning and fix
no …/Shotlist/shotlist.json; run `shotlist init` first	No project here. Run shotlist init, or pass --project-dir.
…/shotlist.json isn't valid: …	The JSON doesn’t parse, or a key is missing or the wrong type. The rest names it.
shotlist.json version … isn't supported; this Shotlist reads version 1	Set "version": 1.
app needs a "project" or "workspace"	Add one to app.
unknown slot '…'; known slots: iphone-6.9, iphone-6.3, ipad-13, iphone-duo-outer, iphone-duo-inner	Use one of those.
unknown appearance '…'; use light or dark	In appearances or a sequence entry.
sequence is empty	Add an entry.
sequence has … scenes; App Store Connect takes at most 10 per size	Remove entries.
fixedDate '…' isn't an ISO 8601 date such as 2026-06-14T10:30:00Z	Include a time and a zone.
--slots names …, which shotlist.json doesn't list (also --locales, --scenes)	A filter named something not in shotlist.json.
the filters match no cells	The filters together match nothing, for example a scene limited to an appearance you didn’t capture.

doctor

Message	Meaning and fix
xcodebuild didn't run; install Xcode and run `sudo xcode-select -s /Applications/Xcode.app`	No Xcode, or the command-line tools are selected instead.
Xcode …; Shotlist needs Xcode 27 or later (Device Hub, iPhone Duo)	Update Xcode.
… not found next to Shotlist/	The project or workspace path is wrong. It’s relative to the folder that holds Shotlist/.
no installed iOS runtime supports …; install it in Xcode › Settings › Components	Install the iOS 27 runtimes. The Duo needs iOS 27.1.
simctl didn't answer: …	CoreSimulator isn’t responding. Run xcrun simctl list devices yourself; restarting the Mac usually clears it.
… GB free; each simulator takes 2 to 6 GB	A warning below 15 GB, a failure below 5 GB. Free some space.
guided: you'll be asked to unfold the Duo once per run…	A warning: Accessibility isn’t granted. See iPhone Duo.
the Mac's screen is locked: iPhone Duo inner-display captures need it unlocked…	Unlock before capturing the inner display.
not found at the usual path inside Xcode.app (Device Hub)	Xcode is somewhere else, or incomplete. Duo unfolding may not work.

Capture: before the first cell

Message	Meaning and fix
another `shotlist capture` is running on this Mac; captures share simulators, so wait for it to finish	One capture at a time per Mac. Wait, or find the other process with pgrep -fl shotlist. Exit code 2.
can't open the capture lock at …	~/Library/Caches/app.shotlist/ isn’t writable. Check its permissions.
the build failed: …	xcodebuild failed. The message quotes the command and its error lines; run the command for the full output.
the build failed: … Macro "…" from package "…" must be enabled before it can be used	Xcode hasn’t been allowed to run that package’s macros, such as @Shot. Build the app once in Xcode and choose Trust & Enable. On CI, see Package macros.
@Shot writes body itself: rename body to root, and make it your app's root view	@Shot writes body, so your App can’t have one. Rename it to root and return your root view (what was inside the WindowGroup), or remove @Shot and host the scenes yourself. See SwiftUI with @Shot.
@Shot needs `var root: some View`: your app's root view, which it shows in a WindowGroup	Add var root: some View with your root view.
@Shot goes on your app's App struct	@Shot is on something other than a struct. Move it to the App.
unknown attribute 'Shot' in a Release build	import ShotlistMacros is inside #if DEBUG. Move it out: @Shot has to exist in Release too.
cannot find 'Screenshots' in scope, from macro Shot	@Shot reads your scenes from Screenshots.scenes, as shotlist init writes them. Rename your scenes type to Screenshots, or host the scenes yourself.
no app with bundle ID … in …; check app.bundleID and app.scheme in shotlist.json	The build (or the last build, with --skip-build) has no app with that bundle ID. Check both keys, or build without --skip-build.
… isn't an app bundle	--app doesn’t point at a .app folder with an Info.plist.
no installed iOS runtime supports …; install one in Xcode › Settings › Components	No runtime for that slot’s device. Its cells fail; others carry on.
…: couldn't prepare the simulator: …	A simulator couldn’t be created, booted or set up. Every cell on it fails with this reason.
… has no display '…' for …; it has …	The simulator has a different set of displays than the slot expects. Update Shotlist.
…'s … framebuffer is … × …, which … doesn't accept (…). The slot table needs updating.	A simulator produced a size the slot doesn’t accept. Update Shotlist.
simctl create returned '…', not a UDID	simctl misbehaved. Run xcrun simctl list devices to check CoreSimulator is healthy.
the simulator region is still … after setting en_US; the status bar may read 09:41	A warning. Erase that simulator and capture again.
…: … is for an older runtime and is no longer used	Information: a newer runtime is installed, so a new simulator was made. Delete the old one if you like.

Capture: the app and the engine

Message	Meaning and fix
timed out after 90 s waiting for hello from the app (pid …) on the control channel	The app launched but never contacted the engine. Check that the host is installed when Shotlist.isActive, that Screenshots.swift is in the app target, and that the configuration defines DEBUG. Also check the app doesn’t crash at launch.
no hello from pid …	As above.
rejected: … speaks control protocol …; this engine speaks …. Update ShotlistKit or the engine so they match.	The app’s ShotlistKit and your shotlist are different versions. Update the package or the CLI.
rejected: … presented the wrong session token; it wasn't launched by this run	A copy of the app from another run connected. Shotlist ignores it; if this repeats, quit stray simulators and capture again.
couldn't read a pid from simctl launch output '…'	simctl launch failed twice. Check the app installs and launches on the simulator.
command failed (exit …): xcrun simctl …	A simulator command failed after its retry. The exact command and its output follow.
the app (pid …) closed the control channel while waiting for …; it may have crashed	The app crashed or quit. Find the crash in the simulator’s logs or by running the scene from Xcode. The next cell relaunches it.
Two Shotlist scenes share the id '…'	The app stops at launch: two scenes in Screenshots.scenes have the same id. Rename one.
retrying once after: …	A warning: a flaky command is being retried.
the simulator is …; booting it again	A warning: the simulator went away mid-run. Shotlist is recovering it.
couldn't recover the simulator: …	Recovery failed; the rest of that simulator’s cells fail. Check shotlist doctor, then capture the gap.

Capture: a scene

Each of these fails one cell and is prefixed scene '<id>' failed:.

Message	Meaning and fix
the app has no scene with this id; it has … (or the app has no scene '…'; it has …)	sequence names a scene that isn’t in Screenshots.scenes. Check the spelling, or that the app was rebuilt.
not ready after … s: open hold '…'	A hold was never released. Find it by its label; release it, or check its work finishes.
not ready after … s: pending GET https://…	A request never got a response. Usually a request through a session ShotlistKit answers, stuck elsewhere; check the URL.
not ready after … s: nothing open (the scene never appeared)	Nothing was open, but the scene didn’t finish: its view never appeared, or prepare was still running. Check prepare, and that the view is shown. Raise capture.sceneTimeout if it’s genuinely slow.
No fixture for GET … (…); looked in Fixtures/…/GET/… and Fixtures/shared/GET/…	A request had no fixture. Add a file at one of the paths named.
… failed: … (a request)	A request through ShotlistKit failed for another reason, given after the colon.
the app didn't accept …; check its URL scheme	A link scene’s URL wasn’t accepted: register the scheme in Info.plist (CFBundleURLTypes).
timed out after … s waiting for ready from scene '…'	The engine’s backstop, 15 s after the scene’s own timeout. The app stopped responding.
Any other error	Thrown by your scene’s prepare or builder; the description is yours.

Capture: the image

Message	Meaning and fix
the screen kept changing across 13 captures; something on it is animating (a spinner, a looping animation or a ticking time)	See Animation and live content.
captured … × …, which … doesn't accept	The capture came out at an unexpected size, for example the Duo in the wrong orientation. Capture again; if it repeats, report it.
the capture is blank (mean luminance …); the scene drew nothing	The screen was one flat colour. Usually a view that hasn’t loaded, or content hidden behind an empty state.
… still has an alpha channel after flattening	Flattening failed. Capture again; if it repeats, report it.
the scene doesn't list the open posture (or closed)	Not an error: the cell is skipped (“Not used here”) because the scene’s postures leave out this display.

Capture: iPhone Duo

Message	Meaning and fix
the Mac's screen was locked, so the iPhone Duo couldn't be unfolded; run `shotlist capture --slots iphone-duo-inner` while you're at the Mac	Inner cells fail at once while the screen is locked. Do as it says.
Accessibility access isn't granted to this process, so the Duo fold is a guided step…	A warning. Grant Accessibility, or click Open when asked.
In Device Hub, set '…' to Open: click the Open posture button in its window. Shotlist continues as soon as the app moves.	A prompt: do it.
couldn't drive Device Hub's posture buttons (…), so the Duo fold is a guided step	A warning: automation failed, so you’ll be asked instead.
Device Hub didn't show a window for '…' within 60 s	Open Device Hub yourself and capture again.
Device Hub's '…' button wasn't found; its labels may be localised or its layout changed	Device Hub isn’t in English, or Xcode changed it. Use the guided step.
pressing Device Hub's '…' button failed (AXError …)	Accessibility refused the press. Check the permission.
couldn't set the Duo to …: …	The fold or unfold didn’t happen. Every cell of that phase fails with the reason.
timed out after 900 s waiting for the app to move to the inner display	Nobody unfolded it in the guided step’s 15 minutes.
timed out after 20 s waiting for the app to move to the inner display	An automatic press didn’t unfold it. Check the Duo’s window in Device Hub.
timed out after … s waiting for portrait orientation	The rotation didn’t happen.
the iPhone Duo can't be set to … while the Mac's screen is locked	Unlock the Mac.

Captions

Message	Meaning and fix
Captions.xcstrings isn't a String Catalog	The file isn’t valid JSON in String Catalog form. Open it in Xcode to repair it, or restore it from Git.
Captions.xcstrings has no en captions to translate; write them first (keys like scene.<id>.caption)	captions draft needs source-language captions.
no on-device en→de translation is installed, and no Claude API credential (ANTHROPIC_API_KEY or `ant auth login`)	That locale was skipped. Install the language in System Settings › General › Language & Region › Translation Languages, or set ANTHROPIC_API_KEY.
the Claude API answered HTTP …: …	The API refused the request. 401 means a bad key; the rest of the message is the API’s explanation.
the Claude API declined to translate these captions into …	Translate that locale yourself.
the Claude API returned no text (stop reason …)	Try again, or translate it yourself.

Compose

Message	Meaning and fix
no manifest at …; run `shotlist capture` first	Nothing captured yet.
not captured; run `shotlist capture`	A cell compose needs has no capture.
its capture failed: …	Fix the capture first.
no caption for scene '…' in …: add scene.….caption to Captions.xcstrings, or run `shotlist captions draft`	Add the caption.
caption overflow in …, scene '…': "…" doesn't fit: … Shorten it for … in Captions.xcstrings, or add a line break.	See Text fitting. The reasons: the word "…" is wider than the caption box, it needs … lines and the template allows …, it's … px tall and the caption area is … px, each even at the minimum size (… px).
subtitle overflow in …, scene '…': …	The same, for a subtitle.
title overflow in …: …	The same, for creative art.
no template '…': add Shotlist/Templates/….json or use one of caption-bottom, caption-top, full-bleed, header-brand, search-hero, split	Fix the name, or add the file.
Templates/….json isn't a valid template: …	A required key is missing or the wrong type. See Your own templates.
can't read raw/…	The capture file is missing or damaged. Capture that cell again.
no creative.header.title caption in …	Add it.
no creative.search.title (or caption for '…') in …	Add either.
no capture of '…' to put in the search art	The search scene isn’t in sequence, or its capture failed for that slot.
search art headline in … is … px at search-results size; 14 px or more reads reliably	A warning. Shorten the headline, or use a larger caption.
content lint, … …: …	A warning from compose; verify fails on it. See Content rules.
ImageRenderer produced no image at … × …, … is … × …, not … × …, … has an alpha channel, … isn't a readable PNG	Rendering failed its own check. Compose again; if it repeats, report it with the template.

Verify

See Verifying output for every check. The messages:

Message	Meaning and fix
no manifest at …; run `shotlist capture` first	Capture first.
not captured; run `shotlist capture`	A cell in the matrix has no capture.
capture failed: …	Fix and recapture that cell.
the file is missing, not a PNG	A file the manifest names isn’t there. Capture or compose again.
has an alpha channel (PNG colour type …); Apple rejects transparency	Shouldn’t happen with Shotlist’s own output. Recompose.
… × … isn't an accepted … size (…)	The wrong size for that slot.
… screenshots; App Store Connect takes 1 to 10 per size	Too many: more than 10 entries in sequence reach this size and appearance. Trim the sequence or split it by slot.
every capture is identical to …'s. The app probably doesn't declare … (add it to a String Catalog or an .lproj), so iOS showed another language	Declare the language in the app.
no composed screenshots; run `shotlist compose`	Compose.
… has no caption for scene '…' (scene.….caption)	Add it.
… '…': “…” is a machine draft nobody has reviewed. Check it, then `shotlist captions review --locales …`, or pass --allow-unreviewed	Get it checked, then mark it reviewed.
… … breaks Apple's content rules: …: “…”	Reword it.
missing; run `shotlist compose`	A creative asset is missing.
… × …; Apple wants … × …	A creative asset is the wrong size.

Publish

Message	Meaning and fix
Not publishing: `shotlist verify` has … problem(s).	--apply refused. Fix what verify reports.
no App Store Connect key: set ASC_KEY_ID and ASC_ISSUER_ID…	Set up the key. See App Store Connect.
no App Store Connect issuer: set ASC_ISSUER_ID or add issuerID to ~/.config/shotlist/asc.json	Add the Issuer ID.
no App Store Connect key at …	The .p8 isn’t at that path.
… is readable by other users (mode …); run `chmod 600 …` first	Do so.
can't read the key at …	The file exists but can’t be read. Check its owner.
the App Store Connect key … isn't a valid .p8 (PKCS #8 P-256) key	Use the file exactly as Apple gave it.
App Store Connect rejected the key … (401). Check the Mac's clock, and that the key hasn't been revoked in Users and Access › Integrations.	Set the clock automatically; check the key.
no app with bundle ID … in this App Store Connect team	Check app.bundleID, set app.ascAppID, or use a key from the right team.
no editable App Store version: … is …. Create the next version in App Store Connect, then plan again.	Create the version.
no version … in App Store Connect	Check the --store-version string.
version … is …; App Store Connect only accepts screenshot changes on an editable version	--apply with a --store-version that isn’t editable.
version … has no … localisation; add it in App Store Connect	A blocked row. Add the localisation, or map the locale with app.ascLocales.
… new + … not uploaded by Shotlist would exceed 10; pass --prune to replace them	A blocked row: too many screenshots in the set.
a placement Shotlist didn't make is live; pass --prune to replace it	A blocked creative row.
App Store Connect couldn't process …: …	Apple rejected the upload.
… was still processing after 5 minutes	Run --apply again later.
App Store Connect couldn't process … (creative)	Apple rejected the art.
App Store Connect rate limit; waiting … s	A warning. Shotlist waits and retries.
App Store Connect answered … to …; retrying once	A warning: a server error, being retried.
… … failed with HTTP …: …	Apple’s explanation follows.
uploading part at offset … failed with HTTP …	A network problem during upload. Run --apply again.
App Store Connect returned no resource, no HTTP response from …	A network problem. Try again.
add an App Store Connect key first	In the Mac app: add the key in the Publish inspector.

Licence

Message	Meaning and fix
You'll need a Shotlist subscription to …	Start a trial or activate a key. See Subscription.
That key wasn't found. Check you've copied all of it.	Copy the whole key.
This key can't be used on this Mac. It may already be in use on 3 Macs, or its subscription may have ended.	Deactivate another Mac, or check the subscription.
That key is for a different app.	Use your Shotlist key.
Couldn't reach Polar to check the key. Check you're online and try again.	Go online.
This copy of Shotlist isn't set up to take licence keys.	This build has no subscription set up. Download Shotlist from the Shotlist page.
! Couldn't reach Polar lately; your subscription keeps working until …	A warning: offline, within the 14 days.
! Couldn't reach Polar to check SHOTLIST_LICENSE_KEY; carrying on.	A warning in CI.
Shotlist hasn't reached Polar for over two weeks. Go online and try again.	Paid actions are paused until a check succeeds.

Still stuck

• Run shotlist doctor and fix any failures.
• Capture just the failing cell with --slots, --locales and --scenes, and read its reason in full.
• Run the scene in Xcode: put RootView(…) exactly as the scene builds it into a preview or a temporary root, to see the screen and any errors.
• For a build or simulator problem, run the command quoted in the log yourself.