Troubleshooting

Every error ShowTake's tools return, what it means and the exact fix, plus the doctor check your agent runs first.

Your agent usually fixes problems by itself: every ShowTake error tells it what went wrong and what to do, step by step. This page lists the same information, so you can follow along when the agent asks you for something.

How errors work

Every failed tool call returns JSON like this:

{
  "code": "runtime_missing",
  "message": "No iOS Simulator runtime is installed (a fresh Xcode ships without one).",
  "fix": [
    { "action": "shell", "text": "Download the iOS runtime (several GB, 5-20 min; no password needed).", "command": "xcodebuild -downloadPlatform iOS" },
    { "action": "tool", "text": "Check it is installed (ios_runtimes).", "tool": "list_targets" }
  ],
  "retryable": true,
  "needs_user": false,
  "docs": "https://showtake.app/docs/troubleshooting#runtime-missing"
}

fix is an ordered list. shell steps are commands the agent runs, tool steps are ShowTake tool calls, edit_project means a change in your code, open_url opens a System Settings pane, ask_user is a question for you.
needs_user: true means only you can do it: a password prompt, a switch in System Settings, installing Xcode, or a payment. The agent then tells you the tell_user sentence and waits. Commands marked needs_password use sudo; the agent gives them to you to run in Terminal instead of running them itself.
details carries the evidence: the closest matching elements, compiler errors with file and line, the crash log and its key lines, the installed simulator runtimes.
ShowTake never waits on a hidden prompt. If macOS would ask something, the tool returns an error that says so.

The doctor check

The doctor tool checks everything ShowTake depends on in a few seconds: macOS, Xcode (selected, license accepted, first-launch setup done), iOS Simulator runtimes and device types, free disk space, ShowTake's built-in automation helper, Accessibility and Screen Recording, displays, the app and MCP server versions, the license and the connection to showtake.app. Each problem comes back with the same fix as the error below. prepare_ios and prepare_macos run the same checks first, so a broken setup fails in seconds rather than after a long build.

Ask your agent "run the ShowTake doctor" any time something seems off.

Mac and ShowTake setup

`macos_too_old`

macOS is too old. ShowTake needs macOS 26 (Tahoe) or later; doctor reports the running version.

Ask the user to update macOS in System Settings > General > Software Update (ShowTake needs macOS 26 or later).
Open Software Update for the user. open "x-apple.systempreferences:com.apple.Software-Update-Settings.extension"

Needs you: the agent asks: “ShowTake needs macOS 26 or later. Please update macOS in System Settings > General > Software Update, then I'll continue.”

`disk_low`

Low disk space. Less than 10 GB free on the volume that holds DerivedData or simulator data (builds and simulator clones need several GB).

Delete simulators whose runtime is gone (safe). xcrun simctl delete unavailable
Delete ShowTake's own build cache (rebuilt on the next prepare_ios). rm -rf ~/Library/Caches/ShowTake/DerivedData
If still short, ask the user before deleting Xcode's DerivedData (~/Library/Developer/Xcode/DerivedData, caches only) or old takes in ~/Movies/ShowTake.
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

The agent retries after the fix.

`disk_full`

Disk full. A write failed with "No space left on device" (recording, export, build or simulator clone).

Cause: The disk ran out of space; the file being written is incomplete.

Delete simulators whose runtime is gone (safe). xcrun simctl delete unavailable
Delete ShowTake's own build cache (rebuilt on the next prepare_ios). rm -rf ~/Library/Caches/ShowTake/DerivedData
Check how much space is free (need 10 GB or more). df -h ~
If still short, ask the user what to delete; then retry the call. A take that was recording must be filmed again.

The agent retries after the fix.

`dependency_missing`

A required tool is missing. A command-line tool ShowTake runs is not installed.

Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor
Follow the fix doctor gives for the failed check.

`axe_missing`

Built-in AXe is missing. ShowTake's bundled iOS automation helper (Contents/Helpers/axe) is missing, or the AXePath override points nowhere.

If an AXePath override is set, remove it (ShowTake then uses its bundled copy). defaults delete app.showtake.ShowTake AXePath
Otherwise reinstall ShowTake (the bundle is damaged). brew reinstall --cask orchestero/tap/showtake
Without Homebrew: download https://showtake.app/download and replace /Applications/ShowTake.app.

The agent retries after the fix.

`axe_quarantined`

AXe is quarantined. The AXe binary carries the com.apple.quarantine flag (copied from a download), so macOS blocks it or shows a hidden prompt.

Remove the quarantine flag from the AXe override (never needed for the bundled copy of a notarized install). xattr -d com.apple.quarantine "$(defaults read app.showtake.ShowTake AXePath)"
Or drop the override and use the bundled AXe. defaults delete app.showtake.ShowTake AXePath

The agent retries after the fix.

`axe_broken`

AXe does not run. AXe exists but fails to start (killed by code signing, wrong architecture, or a damaged copy).

Check the signature of the AXe in use. codesign --verify --verbose "/Applications/ShowTake.app/Contents/Helpers/axe"
Remove an AXePath override if one is set. defaults delete app.showtake.ShowTake AXePath
Reinstall ShowTake. brew reinstall --cask orchestero/tap/showtake

The agent retries after the fix.

`folder_access_prompt`

macOS is asking about folder access. ShowTake tried to read a folder macOS protects (Desktop, Documents, Downloads, iCloud Drive, an external or network volume) and macOS is showing the user a permission dialog. ShowTake gives up after 3 s instead of hanging.

Ask the user to click Allow in the macOS dialog about ShowTake (it may be behind other windows).
Then retry the same call; macOS remembers the answer.
To avoid it, keep projects outside Desktop, Documents and Downloads (e.g. ~/Developer).

The agent retries after the fix. Needs you: the agent asks: “macOS is asking whether ShowTake may access one of your folders. Please click Allow in that dialog (it may be behind other windows), then tell me.”

`folder_access_denied`

Folder access denied. macOS refused ShowTake access to a protected folder (the user clicked Don't Allow once).

Open Privacy & Security > Files & Folders for the user. open "x-apple.systempreferences:com.apple.preference.security?Privacy_FilesAndFolders"
Ask the user to turn the folder on for ShowTake there, then tell you.
Or work from a folder outside Desktop, Documents and Downloads (e.g. ~/Developer).

The agent retries after the fix. Needs you: the agent asks: “ShowTake is not allowed to read that folder. In System Settings > Privacy & Security > Files & Folders (I've opened it), turn it on for ShowTake, then tell me.”

`network_unreachable`

No connection to showtake.app. api.showtake.app did not answer (offline, VPN, firewall or proxy). Filming works offline; license refresh and purchases do not.

Check the connection. curl -sS -m 5 -o /dev/null -w '%{http_code}\n' https://api.showtake.app/healthz
Keep working: Pro stays on offline for 30 days after the last refresh. Purchases need the connection.

The agent retries after the fix.

Xcode

`xcode_missing`

Xcode is not installed. iOS takes need the full Xcode app (simulators, xcodebuild). Mac takes of a prebuilt app do not.

Ask the user to install Xcode from the Mac App Store (about 10 GB, needs their Apple Account), open it once, then tell you.
Open Xcode's App Store page for the user. open "macappstore://apps.apple.com/app/id497799835"
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

Needs you: the agent asks: “ShowTake needs Xcode to run your iOS app in the Simulator. Please install Xcode from the Mac App Store (I've opened its page), open it once, then tell me.”

`xcode_select_clt`

Command Line Tools selected instead of Xcode. xcode-select points at /Library/Developer/CommandLineTools, so xcodebuild and simctl are unavailable although Xcode is installed.

Point the developer directory at Xcode (asks for the user's password; the user runs it in Terminal). sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer (asks for your password)
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

Needs you: the agent asks: “Your Mac uses the Command Line Tools instead of Xcode. Please run this in Terminal and enter your password: sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer”

`xcode_license`

Xcode license not accepted. xcodebuild refuses to run until the Xcode license is accepted.

Accept the license (asks for the user's password; the user runs it in Terminal). sudo xcodebuild -license accept (asks for your password)
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

Needs you: the agent asks: “Xcode's license has not been accepted yet. Please run this in Terminal and enter your password: sudo xcodebuild -license accept”

`xcode_first_launch`

Xcode first-launch setup not done. Xcode's first-launch components are missing (a new or updated Xcode that was never opened).

Install the components (asks for the user's password; or the user opens Xcode once and clicks Install). sudo xcodebuild -runFirstLaunch (asks for your password)
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

Needs you: the agent asks: “Xcode still needs its first-launch setup. Please open Xcode once and click Install, or run this in Terminal: sudo xcodebuild -runFirstLaunch”

`xcode_broken`

xcodebuild does not run. xcodebuild exited with an error or hung before doing anything (damaged or half-updated Xcode).

See the error. xcodebuild -version
Check which developer directory is selected. xcode-select -p
If Xcode is damaged or mid-update, ask the user to finish the update in the App Store or reinstall Xcode.

The agent retries after the fix.

iOS Simulator

`runtime_missing`

No iOS Simulator runtime. Xcode has no usable iOS Simulator runtime (fresh Xcode installs ship without one), or not the requested os version.

Download the iOS runtime (several GB, 5-20 min; no password needed). xcodebuild -downloadPlatform iOS
Check it is installed (ios_runtimes). tool list_targets
Then prepare again (omit os to use the newest installed runtime). tool prepare_ios

The agent retries after the fix.

`runtime_too_old`

iOS runtime older than the app's deployment target. The app's MinimumOSVersion is newer than every installed iOS Simulator runtime, so it cannot install.

Download the newest iOS runtime. xcodebuild -downloadPlatform iOS
Or lower IPHONEOS_DEPLOYMENT_TARGET of the app target to the installed runtime version (only if the user agrees).
Then prepare again. tool prepare_ios

The agent retries after the fix.

`device_type_missing`

Unknown simulator device type. The device passed to prepare_ios is not a device type this Xcode knows (details.closest lists the nearest names).

Use one of the names in details.closest or list_targets inventory.ios_device_types. tool list_targets
Prepare again with that device (or omit it for the default). tool prepare_ios

The agent retries after the fix.

`simulator_boot_failed`

The simulator did not boot. simctl boot or bootstatus failed or hung for ShowTake's simulator clone.

Shut ShowTake's clone down (details.udid). xcrun simctl shutdown <udid>
Retry prepare_ios (a new clone is made if needed). tool prepare_ios
If it fails again, the CoreSimulator service is stale: see coresimulator_stale.

The agent retries after the fix.

`coresimulator_stale`

CoreSimulator service is stale. simctl hangs or reports a CoreSimulator version mismatch (typical right after an Xcode update).

Restart the simulator service (closes every open simulator, also the user's own). killall -9 com.apple.CoreSimulator.CoreSimulatorService
Check simctl answers again. xcrun simctl list runtimes
If the error mentions an out-of-date CoreSimulator, ask the user to open Xcode once (it installs the matching components) or restart the Mac.

The agent retries after the fix.

`simulator_accessibility_timeout`

Simulator accessibility did not start. A new simulator clone did not answer accessibility queries within minutes (the Mac is overloaded or the first boot is slow).

Wait a minute; the clone keeps settling in the background.
Retry prepare_ios: the settled clone is reused. tool prepare_ios

The agent retries after the fix.

Project and scheme

`project_not_found`

No Xcode project found. project does not exist, or no .xcodeproj/.xcworkspace is under the working directory.

List projects under a folder (path). tool list_targets {"path":"."}
Prepare with the exact project path from that list. tool prepare_ios

The agent retries after the fix.

`project_ambiguous`

Several projects found. More than one project or workspace is under the working directory and project was not given (details.found lists them).

Pick one from details.found; prefer the .xcworkspace when a project has one (CocoaPods, SPM workspaces).
Prepare with that project and its scheme. tool prepare_ios

The agent retries after the fix.

`scheme_required`

Scheme not given. prepare_ios needs scheme; details.schemes lists the project's schemes.

Prepare again with the app's scheme from details.schemes (usually named like the app, not a test or framework scheme). tool prepare_ios

The agent retries after the fix.

`scheme_not_found`

Scheme not found. The project has no scheme with that name (typo, or the scheme is not shared). details.schemes lists them, details.closest the nearest.

Prepare again with a scheme from details.closest / details.schemes. tool prepare_ios
If the app's scheme is missing, it is not shared: in Xcode, Product > Scheme > Manage Schemes, tick Shared (creates xcshareddata/xcschemes/.xcscheme).

The agent retries after the fix.

`no_app_target`

Scheme builds no iOS app. The scheme built, but it produces no .app (a framework, test or macOS scheme).

List the schemes and pick the app's. tool list_targets
For a Mac app use prepare_macos with the built .app instead.

The agent retries after the fix.

Building the app

`build_failed`

The build failed. xcodebuild failed for a reason ShowTake could not classify; details.log_tail holds the end of the log.

Read details.errors / details.log_tail.
Reproduce the build (same flags ShowTake uses) to see the full log. xcodebuild -scheme <scheme> -configuration Release -destination 'generic/platform=iOS Simulator' build
Fix the cause, then prepare again. tool prepare_ios

The agent retries after the fix.

`compile_error`

The app does not compile. Swift/Objective-C compiler errors; details.errors lists the first ones with file:line.

Fix the errors in details.errors (they are in the user's code), or ask the user whether the branch is meant to build.
Prepare again. tool prepare_ios

The agent retries after the fix.

`signing_failed`

Code signing failed for the simulator build. The project forces signing settings (a team, profile or entitlements) that a simulator build cannot satisfy.

ShowTake builds with ad-hoc signing (CODE_SIGN_IDENTITY=-, no team). A build phase or xcconfig that hard-codes a profile overrides it.
Make the simulator build not require a provisioning profile (e.g. set CODE_SIGNING_REQUIRED/PROVISIONING_PROFILE_SPECIFIER only for sdk=iphoneos*), or ask the user.
Or build it yourself for the simulator and pass app_path. tool prepare_ios

The agent retries after the fix.

`packages_unresolved`

Swift packages could not be resolved. Swift Package Manager failed to fetch or resolve dependencies (network, private repo, or Package.resolved conflict).

Resolve packages and read the error. xcodebuild -resolvePackageDependencies -scheme <scheme>
Private repositories need git credentials for the user's account (ask the user); offline needs a network.
Prepare again. tool prepare_ios

The agent retries after the fix.

`pods_missing`

CocoaPods not installed for this project. The project has a Podfile but Pods are missing or out of date, or the .xcodeproj was given instead of the .xcworkspace.

Install the pods (in the folder with the Podfile). pod install
Prepare with the .xcworkspace, not the .xcodeproj. tool prepare_ios

The agent retries after the fix.

`carthage_missing`

Carthage frameworks missing. The project links Carthage frameworks that are not built (Carthage/Build is missing).

Build the Carthage dependencies for the simulator. carthage bootstrap --platform iOS --use-xcframeworks
Prepare again. tool prepare_ios

The agent retries after the fix.

`swift_version_mismatch`

Swift or Xcode version mismatch. The project or a dependency needs a different Swift/Xcode version ("compiled with a newer version", unknown language mode, unsupported swift-tools-version).

Check the installed Xcode and Swift. xcodebuild -version && swift --version
Ask the user which Xcode the project needs; installing another Xcode is the user's call.

Needs you: the agent asks: “Your project needs a different Xcode or Swift version than the one installed. Which Xcode version does this project use?”

The app at launch

`launch_failed`

The app did not start. The app was installed but did not come to the front (or simctl launch failed).

Relaunch it once. tool launch_app {"fresh":true}
If it keeps failing, check launch_args/env, and look for a crash (app_crashed carries the crash log).

The agent retries after the fix.

`app_crashed`

The app crashed. The app quit right after launch or during a step; details.crash_log is the report, details.crash_tail its key lines.

Read details.exception and details.crash_tail: the crashing frames are usually in the user's code.
Fix the crash (or pass the launch_args / env the app needs, e.g. a demo mode that skips missing config).
Prepare or relaunch again. tool launch_app {"fresh":true}

The agent retries after the fix.

`login_wall`

A login or onboarding screen blocks the app. Reported in warnings when the first screen looks like sign-in or onboarding.

Look for a demo or UI-test mode in the code (launch arguments such as -UITests, -demo, -skipOnboarding; environment flags) and pass it as prepare_ios launch_args / env.
If there is none, ask the user for demo-mode launch arguments or a test account. Never guess credentials.

`accessibility_empty`

The screen has no accessible elements. The app's screen reports no or almost no accessibility elements (custom drawing, game engines, canvases, or a still-loading screen).

Observe again after a moment (it may still be loading). tool observe
Tap by points (x, y from a screenshot) as a fallback.
Suggest adding accessibility identifiers: SwiftUI .accessibilityIdentifier("add"), UIKit view.accessibilityIdentifier = "add".

The agent retries after the fix.

Finding elements

`element_not_found`

No element matches. The id/label/value matches nothing on the current screen. details.closest lists similar elements, details.screen the current screen.

Pick the element from details.closest or details.screen and target it by its id (or label).
If details.keyboard is true, the keyboard may cover it: press dismiss_keyboard first. If details.alert is true, an alert is on top: answer it first.

The agent retries after the fix.

`stale_index`

Element number from an older screen. index came from a screen that has changed since (details is the current screen).

Target again from details (the current screen), preferably by id or label.

The agent retries after the fix.

`alert_blocking`

An alert or permission dialog is in the way. A system alert (permission request) or app alert covers the screen; only its buttons are reachable (details.buttons).

Tap one of details.buttons to answer it (e.g. "Allow").
For permission prompts, pre-grant them instead: prepare_ios with privacy (photos, camera, location, contacts, microphone...). tool prepare_ios {"privacy":["photos"]}

The agent retries after the fix.

`no_focused_field`

No text field is focused. type_text without target while no keyboard is shown.

Pass the field as target (ShowTake taps it first). tool type_text

The agent retries after the fix.

Takes and sessions

`not_prepared`

No prepared app. A driving tool was called before prepare_ios / prepare_macos, or the session was replaced (ShowTake relaunched, or another agent prepared another app).

Prepare the app again. tool prepare_ios
If another agent is using ShowTake on this Mac at the same time, wait for it to finish: one app is driven at a time.

The agent retries after the fix.

`take_running`

A take is already recording. start_take, prepare or launch_app while a take records.

End the running take first (it is saved, not lost). tool end_take

The agent retries after the fix.

`no_take`

No take is recording. end_take or mark without a running take.

Start one. tool start_take

`caption_required`

Step needs a caption. An action during a take had no caption.

Repeat the call with a viewer-facing caption of at most 8 words.

The agent retries after the fix.

`recorder_failed`

Recording failed. The simulator or window recorder did not start, stopped early or delivered no frames.

End the take if one is open, then relaunch and record again. tool end_take
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor
Mac: the window must be visible on screen (not minimised or on another Space); Screen Recording must be granted.

The agent retries after the fix.

`timeout`

Timed out. A wait_for or a command ran past its limit.

Look at the screen to see what it shows instead. tool observe
For slow network content, use demo data (launch_args) so takes do not depend on the network.

The agent retries after the fix.

`driver`

The automation layer failed. A touch, key or accessibility call failed inside the simulator or Mac app.

Retry the step once. tool observe
If it repeats, relaunch the app. tool launch_app {"fresh":true}
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

The agent retries after the fix.

`command_failed`

A system command failed. simctl, xcodebuild or another tool returned an error (the message carries its stderr).

Read the message.
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

The agent retries after the fix.

Mac apps

`permission_missing`

macOS permission missing. ShowTake lacks Accessibility (to press buttons and read the UI) or Screen Recording (to film the window). details.missing names which.

Open the Accessibility pane for the user. open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
Open the Screen Recording pane for the user. open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
Ask the user to turn ShowTake on there (macOS may ask them to quit and reopen ShowTake), then tell you.
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

The agent retries after the fix. Needs you: the agent asks: “macOS needs your OK once: in System Settings > Privacy & Security (I've opened it), turn on ShowTake under Accessibility and Screen & System Audio Recording, then tell me.”

`mac_app_not_found`

Mac app not found. app_path does not exist or is not an app, or no installed app has that bundle_id.

See running Mac apps and their paths. tool list_targets
Find the app. mdfind "kMDItemContentType == 'com.apple.application-bundle'" -name <AppName>
Or build it first and use the .app from the build folder. xcodebuild -scheme <scheme> -configuration Release -derivedDataPath build build

The agent retries after the fix.

`mac_no_window`

The Mac app has no window. The app runs but shows no window (closed, minimised, still launching, or a menu-bar-only app).

Relaunch it. tool launch_app
If it is minimised or on another Space, ask the user to bring it to the current desktop. Menu-bar-only apps cannot be filmed as a window.

The agent retries after the fix.

`window_offscreen`

The window is off screen. The app's window is minimised, hidden or outside every display.

Relaunch the app: ShowTake places and sizes the window again. tool launch_app
With several displays, ShowTake uses the main display (the one with the menu bar).

The agent retries after the fix.

`multiple_displays`

Several displays. Reported by doctor: ShowTake films on the main display.

Nothing to do; keep the filmed app on the main display (the one with the menu bar).

ShowTake app and MCP server

`app_unreachable`

ShowTake.app is not reachable. The MCP server could not reach ShowTake.app over its local socket (not installed, not running, crashed, or blocked at first launch).

Open ShowTake (from /Applications). open -a ShowTake
Check it is installed. ls -d /Applications/ShowTake.app
Not installed: install it. brew install --cask orchestero/tap/showtake
If macOS showed a dialog on first launch ("downloaded from the internet"), ask the user to click Open.
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor

The agent retries after the fix.

`updating`

ShowTake is installing an update. ShowTake is relaunching into a new version.

Wait about 15 s, then retry the call. Prepare again if the call answers not_prepared.

The agent retries after the fix.

`restart_required`

MCP server and app versions do not match. This MCP server process is an older copy than the running ShowTake.app and cannot talk to it.

Ask the user to restart the ShowTake MCP server in their client (Claude Code: /mcp, reconnect showtake).
The MCP command must be /Applications/ShowTake.app/Contents/MacOS/showtake-mcp.

Needs you: the agent asks: “ShowTake was updated; please restart its MCP server in your agent (in Claude Code: /mcp, then reconnect showtake).”

`unsupported_version`

File from a newer ShowTake. A flow or take was written by a newer ShowTake than this one.

Check for an update. tool update_status
Or update with Homebrew. brew upgrade --cask orchestero/tap/showtake

`internal`

Internal error. Something unexpected failed inside ShowTake.

Retry once.
Run doctor: it checks Xcode, simulators, disk, permissions, the app and the license and returns the fix for each problem. tool doctor
If it repeats, tell the user and include the tool name and message; they can send it from ShowTake > Help > Report a Bug.

The agent retries after the fix.

License

`license_required`

Needs ShowTake Pro. The free plan does not include this (non-watermarked or non-X exports, App Previews, screenshot sets, batch replays). details.state says why (free, expired_*, wrong_mac).

Tell the user what needs Pro; do not retry. Free exports: x_16x9 with a watermark.
If they want Pro: upgrade returns a checkout link to give them. tool upgrade {"plan":"pro_yearly"}

Needs you: the agent asks: “This export needs ShowTake Pro. Want me to get you a checkout link? Otherwise I can export the free X 16:9 version with a watermark.”

`license_expired`

Subscription ended. The Pro subscription ended (valid_until passed).

Ask the user to renew at https://showtake.app/manage; ShowTake refreshes by itself afterwards.
Check after they renew. tool license_status

Needs you: the agent asks: “Your ShowTake Pro subscription has ended. You can renew it at https://showtake.app/manage, then I'll continue.”

`license_offline_too_long`

License not refreshed for 30 days. ShowTake could not reach the license server for 30 days, so Pro is paused.

Check the connection to the license server. curl -sS -m 5 https://api.showtake.app/healthz
Once online, ShowTake refreshes within a minute; then call license_status.

The agent retries after the fix.

`license_wrong_mac`

License belongs to another Mac. The stored license was activated on a different Mac (e.g. migrated from a backup).

Ask the user to enter their key again in ShowTake > Settings > License (it activates this Mac).

Needs you: the agent asks: “Your ShowTake license was activated on another Mac. Please enter your key again in ShowTake > Settings > License.”

`seats_full`

Every Mac slot of the license is in use. Activation was refused: the license is active on as many Macs as it allows (details.macs).

Ask the user to free a Mac at https://showtake.app/manage, then enter the key in ShowTake > Settings > License.

Needs you: the agent asks: “Your license is already active on every Mac it allows. Free one at https://showtake.app/manage, then enter your key in ShowTake > Settings > License.”

`purchases_closed`

Purchases are not open. upgrade was called while checkout is closed.

Tell the user; keep working on the free plan.

Render and export

`export_invalid`

Export failed validation. A file broke a store rule (App Preview length, size, fps, captions); each file's validation.failures has the rule and its fix.

Read files[].validation.failures[].fix.
Re-plan with render (trim, captions, cut), then export again. tool render

The agent retries after the fix.

`take_not_found`

Take not found. No take with that take_id in the library.

Use the take_id end_take returned (takes live in the ShowTake library, Settings shows where).

Tool arguments

`bad_request`

Invalid arguments. A parameter is missing, has the wrong type or an unknown value (the message names it).

Fix the arguments as the message says and call again; the tool's input schema lists every parameter.

The agent retries after the fix.

`not_found`

Not found. A file, flow or take named in the call does not exist.

Check the path or name in the message.

`unknown_tool`

Unknown tool. The tool name does not exist in this ShowTake version.

Use a tool from tools/list.

`not_implemented`

Not available in this version. The tool or option is not implemented in this build.

Check for an update. tool update_status

The first iOS take is slow

The first prepare_ios builds your app in Release and creates ShowTake's clean simulator for that device type: 1 to 5 minutes. Later takes reuse both.

The keyboard stays open at the end

Some apps never dismiss their keyboard. ShowTake tries dismiss_keyboard; if the app keeps it, end_take reports a note (not an issue) and the take still counts as clean.

The video has no audio track

Takes record no sound. App Preview exports add a silent stereo track because App Store Connect sometimes refuses files without one.

Still stuck

Email support@showtake.app with the tool name, the error code and its message. Recordings stay on your Mac; we never need them to help.

NextMCP tool reference