Troubleshooting

Symptom → things to check. Entries are grouped by where the problem surfaces. Add new entries as real support questions come in.

Setup & permissions

Mavster opens to the permissions screen and won't move on

Cause: One or more of the four required macOS permissions isn't granted to this copy of Mavster.

Fix: System Settings → Privacy & Security → check Mavster is toggled on under Accessibility, Automation, Screen & System Audio Recording, and Local Network. If you have multiple copies of Mavster (e.g. one in Applications, another in ~/Downloads), remove the stale entries — macOS may have associated the permission with the wrong copy. The setup screen unblocks automatically as soon as everything is granted. → macOS permissions

"Failed to list simulators" error

Cause: Xcode tooling is failing — usually because Xcode Command Line Tools aren't installed or xcode-select -p points at the wrong path.

Fix:

xcode-select -p   # should print /Applications/Xcode.app/Contents/Developer
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Then re-launch Mavster. → iOS tools

No simulators show up in the picker

Cause: Either no iOS runtime is installed, or your only simulators are iPads (iPad simulators are not supported yet).

Fix: Open Xcode → Settings → Platforms → download an iOS runtime. Then Window → Devices and Simulators → Simulators → create an iPhone simulator. → Simulators

Connecting

"Simulator is already in use by Window N"

Cause: Another Mavster window has the simulator.

Fix: Either close that window or pick a different simulator from the picker. The picker also shows which simulators are in use by other windows, so you can see which are free.

Simulator shows "Booted (No Window)" in the picker

Cause: The simulator process is booted but the Simulator app isn't running.

Fix: Click the refresh icon in the picker, or launch the Simulator app from Spotlight. The picker only counts a simulator as "Running" when both the simulator process is up and the Simulator app is alive.

"No simulator is bound to this Mavster window" error

Cause: A test was run before a simulator was selected for this window, or the binding was lost.

Fix: Open the Preview Connection picker and select a simulator. Then run again.

Authoring

$placeholder doesn't appear in the parameter list

Cause: Either the placeholder name has a leading digit ($1stItem is invalid), or it's escaped ($$name is a literal $name), or it's in a field Mavster doesn't scan for parameters.

Fix: Use names that start with a letter or underscore. Confirm the placeholder is in the test name, an interaction instruction, or a Scroll's Until field — those are the only fields scanned. → Parameters & $placeholders

Edit to a User-Defined template didn't propagate to my test

Cause: Either you edited the step locally inside the instance, or you added it inside the instance — both cases are skipped by template propagation.

Fix: If you actually want the template's version, delete the local edit / locally-added step and re-drag the template. If you want both — keep the override; just know that future template edits will skip it. → User-Defined Templates vs. Instances

Running

Test blocked: insufficient credits

Cause: Your account doesn't have enough credits to start a run.

Fix: Open the web app billing page (linked from the alert) and top up. The cached balance may take a moment to refresh on the macOS side after a top-up. → Credits & cost preflight

Test blocked: subscription required

Cause: Your subscription is inactive.

Fix: Open the web app's billing page and reactivate or pick a plan.

Step fails with "no element found" repeatedly

Things to check:

• The instruction may be too vague or uses language the AI can't tie to anything visible. Tighten it to describe a visually identifiable target.

• The element may be offscreen — add a Scroll-with-Until step to bring it into view first.

Self-healing chip is locked

Cause: Self-healing is gated to the Ultra tier.

Fix: Click the locked chip — Mavster opens the standard upsell sheet. If you don't want to upgrade, leave the test on Strict and address flakes with Visual Asserts and Wait Until gates.

Cloud Sync & web app

My project is in the macOS app but not in the web app

Things to check:

• Cloud Sync may not have pushed since the last change. Open the project in the macOS app and trigger a fresh run — Cloud Sync pushes happen as part of normal runs. Then refresh the web app /projects page.

• Confirm you're signed in on the Mac (Account modal → Cloud Backups should read "Enabled").

Still stuck?

If your symptom isn't covered above, email support@mavster.ai. Include what you were trying to do and what happened instead — screenshots help.