Troubleshooting
Start with this. It reports the server, the token, the skill, Xcode, the project and what it is made with, simulators and devices, and every line says what to do next:
appshots check
Signing in#
| The home page says | What to do |
|---|---|
| That Google account is not on the list | The server only admits listed people. Ask whoever runs it to add your address |
| Google sign-in was cancelled | You closed Google's page. Try again |
| That sign-in expired | It took longer than ten minutes, or cookies are blocked. Allow cookies for this site and try again |
| Google has not verified that email address | Use a Google account whose address is verified |
| Too many sign-in attempts | Wait fifteen minutes |
Connecting an agent#
appshots: command not found. The command is in ~/.local/bin, which is not on your PATH. Open a new Terminal window, or add this line to ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
The agent does not know /appshots. Skills are read when a session starts. Start a new session. If it is still missing, run appshots check and look at the Skill: line.
The agent has the skill but no appshots tools. The MCP connection is missing or was added while the session was running. Start a new session. The skill works without MCP too, through appshots call.
401 Unauthorized. The token was revoked, or it belongs to another server. Create a new one under Connect an agent and run the setup command again. See Connect an agent.
The setup command stops at "Node.js 18 or newer is needed". Install Node.js 18 or newer from nodejs.org, then run it again.
You connected through a connector dialog and it asks for a sign-in page. appShots has no OAuth. Add it with a header instead. See Connect an agent.
Capturing#
"simctl failed" or no simulators. Xcode is not installed, or it was never opened. Install it from the App Store, open it once, and let it install the iOS platform.
No booted simulator. Start your app from Xcode, or run appshots run. For an app made with Flutter, React Native, Expo, Capacitor or Tauri, run appshots boot and then the toolkit's own run command.
The build fails in appshots run. Build the app in Xcode first and fix what it reports. If the folder has several projects or schemes, name them with --project and --scheme.
The device is not found. Plug it in, unlock it, and tap Trust on it. Capturing from a device needs Xcode 27 or newer. A simulator works with any recent Xcode.
The status bar shows the wrong time. Add --clean. It works in the simulator only.
The screenshot shows the launch screen. The app needed longer to settle. Add --wait 5.
"Could not capture the window" with --mac. macOS only lets a program take pictures of windows with the Screen Recording permission. Switch on your terminal app under System Settings → Privacy & Security → Screen & System Audio Recording, then quit and reopen the terminal. Or take the window yourself with Shift-Command-4, Space and a click, and upload the file with --as mac. See Mac apps.
--mac does not find the app. The app has to be open with a window on screen. Use its name as the menu bar shows it. The command lists the apps it can see.
appshots run says the project is a Mac app. run is for the iOS Simulator. Start a Mac app your own way and capture its window with appshots capture --mac.
appshots run says there is no Xcode workspace or project. run builds Xcode projects only. An app made with another toolkit and a web app are started by their own command, which appshots check names. See Web apps and other toolkits.
--web says nothing answers at the address. The dev server is not running, or it took another port than usual. Read the address off what it printed when it started.
--web finds no browser. It draws pages with Google Chrome, Chromium, Microsoft Edge or Brave. Install one, or set APPSHOTS_BROWSER to the program of a Chromium browser.
A web page shows a sign-in or an empty state. The browser the command starts has a profile of its own and knows none of your sign-ins. Put sample data in with --init, or keep a session between captures with --profile. See Reach a screen.
A web app's slides have no status bar. The capture leaves its place free. Set Status bar to overlay in the device settings, or "device": {"statusBar": "overlay"} in the theme.
Slides#
A device is empty. The slide names a screenshot that is not uploaded. The render lists the missing names. Upload it under exactly that name.
An iPad slide shows a phone screen. The project has no iPad screenshot under that name. Upload one with the same name. See Sizes.
A Mac screenshot sits in a MacBook, or does not, and it should be the other way. A captured window is shown as a window, and a display-shaped picture in a MacBook. Set Frame in the slide's device settings to MacBook or No frame. See Mac apps.
App Store Connect says the dimensions are wrong. Each display only takes its own sizes. Drag the files of the folder named after that display, as listed in the README.txt of the ZIP. See Render and export.
A screenshot is filed under the wrong device. Change it with the small menu on its thumbnail under Assets in the Studio, or upload it again with --as iphone, --as duo, --as ipad or --as mac.
The headline is tiny. Text shrinks to fit. Shorten the headline, force a line break, or lower the device with the position control.
A screenshot was taken for the wrong device kind. Upload it again, or delete it under Screenshots and upload the right one.
The preview does not show a change the agent made. The Studio checks for changes every few seconds. Reload the page if it stays behind.
Rendering and exporting#
"Two renders are already under way for this account". One render runs and one waits per account. Wait for one to finish, or cancel one with the × beside it under Renders in the sidebar.
"This account has used all of its renders". Every export uses one render, and the account has none left. Ask the person who runs the server for more. See Accounts, tokens and limits.
"The render stopped because the server restarted". The server was updated or restarted while it was drawing. Press Export ZIP again. The stopped render was not counted.
The ZIP did not download when the render was done. It downloads by itself in the tab that started the render. Press Download ZIP under Renders in the sidebar. Some browsers block a download that starts in a background tab.
"Nothing has been rendered yet". appshots pull downloads the last render. Add --render.
The export takes long. Every language and every size is a full pass. The server also renders one job at a time for everybody, so yours may be waiting.
App Store Connect refuses a file. Check that it went onto the display it was made for: the folder name says which. See Sizes.
The files look different from before. A project is drawn by the current version of appShots each time. See Update.
Limits#
"This account is limited to 5 projects", or the same about screenshots or images. Delete what you no longer need. The limits are in Accounts, tokens and limits.
Still stuck#
Write to [email protected] and include what appshots check prints. Leave your token out.