For AI agents: this page is Markdown at https://squiggle.sh/docs/reference/errors.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.
What each squiggle exit code means, so a CI job can act on the number. Plus squiggle explain, which turns an exit code or an error code into the cause and a command that fixes it.
Exit codes
Every squiggle command exits with one of these codes. They don’t change between versions, and squiggle --schema-json lists them too.
Code
Meaning
0
Success. There may be warnings.
1
The run failed: a flow, a suite, a gate or a diff. Also used for an unexpected error in Squiggle itself, which prints a stack trace.
2
A usage error, or a failure Squiggle expected, with a message that says what to do.
3
A licence is needed, has expired, or is over its CI limit.
4
The --timeout you set ran out.
5
No device is available, or another run is using it.
6
Needs an agent: an agent: step had no recording that worked, and no agent was connected. No step failed. Pass --needs-agent fail to exit 1 instead.
What CI should do with each
Codes 0, 1 and 6 are results: the flows ran. The others mean they couldn’t run properly, so fix the machine or the job before you trust the result. Pick what happened to see the code and what squiggle explain says about it:
Pass an exit code or an error code to squiggle explain. It prints what went wrong and, when there is one, a command that fixes it. It works without a licence.
Run squiggle explain on its own to list every code. Add --json to get the same thing as data.
Error codes
Code
What happened, and the fix
E_NO_DEVICE
No simulator is booted (exit 5). Boot one, or pass --udid to choose one.
E_NOT_INJECTED
squiggle up launched the app, but Squiggle didn’t attach to it (exit 5). Quit the app completely and run squiggle up again.
E_STALE_DYLIB
The app is running an older copy of Squiggle than this build (exit 5). Quit the app, then run squiggle up.
E_NO_HOST
The squiggle-host helper that drives the simulator wasn’t found (exit 5). Reinstall Squiggle, or run with --headless.
E_CONNECT
The app never connected on the port the command was waiting on (exit 2). If the message says no app … connected … within 30 s, and this run does not relaunch it, the app isn’t running, often because it crashed, and the run (a bench, a run of several flows, or a report card) doesn’t relaunch it. Run squiggle up, or the flow again with --fresh. Otherwise, run squiggle doctor to check the app is set up and which port it connects to.
E_TIMEOUT
The --timeout ran out (exit 4). Raise it, or give the command less to do.
E_FLOW_PARSE
The flow file isn’t valid YAML, or a step is malformed (exit 2). The message names the line and column. Quote any value that contains #.
E_RUNS_WITH
squiggle flow was given a program whose runWith: names another command, such as squiggle agent branch (exit 2). Run it with the command the message prints.
E_BAD_CHAOS
--chaos or --twin named a profile that doesn’t exist, or --twin none (exit 2). The profiles are slow, flaky, truncated and offline-midstep; --chaos also takes none, and --twin takes all.
E_NO_STUBS
--stubs named a run that isn’t in .squiggle/runs, or one that made no requests (exit 2). Run the flow once with --capture-net, and pass the run id its footer prints.
E_BAD_RUN_COUNT
--fuzz-max or --race-max wasn’t a whole number of runs, 1 or more (exit 2).
E_TWIN_CLASH
--twin, --fuzz or --cache-twins was combined with a flag that also chooses the network or the starting state, such as --chaos, --stubs or --race (exit 2). Pass one of them.
E_RACE_CLASH
--race was combined with --chaos or --stubs (exit 2). --race sets every request’s delay itself; drop the other flag.
E_BAD_CLIFF
--cliff wasn’t VAR=lo..hi, such as N=10..800 (exit 2).
E_BAD_TUNE_WEIGHTS
--tune-weights named a term other than dropped, blank or ms, or a weight that isn’t a number ≥ 0 (exit 2).
E_TUNE_CLASH
--tune was combined with --fresh (exit 2). A relaunch puts each tunable back to its default; drop --fresh.
E_BISECT_STATE_CLASH
--bisect-state was combined with a flag that also chooses what each run starts from, such as --fresh, --cache-twins, --tune or --twin (exit 2). Pass one of them.
E_MATRIX_PLATFORM
--matrix was run against a Mac app (exit 2). Its cells are simulator settings, so it needs an iOS simulator.
E_BISECT_NATIVE
A commit in the squiggle bisect range changes native code or a dependency, which Metro can’t serve (exit 2). Bisect from after that commit with --good, or rebuild and bisect across it by hand.
E_BISECT_USAGE
squiggle bisect got a range it can’t use: --good isn’t an ancestor of --bad, or the range is empty (exit 2).
E_BAKEOFF_USAGE
squiggle bakeoff got an empty --against or a ref that isn’t a commit, or found no app.json (exit 2). Pass --app-dir when the Expo app isn’t at the project root.
E_BAKEOFF_NATIVE
A squiggle bakeoff branch differs from your checkout in native code or a dependency, which Metro can’t serve (exit 2). Compare branches that differ only in JavaScript.
E_BAKEOFF_NO_RUN
squiggle bakeoff started the flow on a revision, but it never ran, for example because the app wasn’t running or the flow name is wrong (exit 1). The error above it says why; fix that and run again.
E_CONTRACTS_PR
squiggle contracts propose --pr couldn’t commit, push or open the pull request; the message shows what git or gh said (exit 1). Run it with --write instead and commit the flows yourself.
E_NO_AGENT
squiggle motion found no Squiggle agent in the app (exit 5). Run squiggle up.
E_MOTION_CAPTURE
squiggle motion couldn’t record the view around the tap, for example because the control to tap wasn’t on screen (exit 1).
E_MOTION_MATCH
The file given to squiggle motion --match couldn’t be read (exit 2). It takes the output of an earlier squiggle motion --json.
E_PROBE_RULE
A squiggle probe rule isn’t one (exit 2): it needs an input, a comparison and a number, such as render.max >= 30, and the input must be one that squiggle probe inputs lists.
E_PROBE_UNSUPPORTED
The app doesn’t take probes (exit 5): it is a release build, which never runs one, or its Squiggle SDK is older than probes.
E_PROBE_REFUSED
The app refused the probe and said why (exit 2), for example a range wider than the input’s, more than 256 instructions in one probe, or more than eight probes at once.
E_PROBE_NO_FIRINGS
squiggle probe export found no recorded firings for that id (exit 2). Run the probe with squiggle probe when first, with the same rules and --id.
E_PROBE_MISMATCH
The rules given to squiggle probe export aren’t the ones the probe ran with (exit 2): re-running them over the recorded firings gives different answers. Pass the same rules, --any and --component as the probe used.
E_LICENSE_REQUIRED
No licence or trial on this Mac (exit 3). Run squiggle activate --trial, or activate a key.
E_LICENSE_EXPIRED
The trial or licence has ended (exit 3). Run squiggle activate with a current key.
E_CI_LIMIT
Too many CI runners are using this licence at once (exit 3). Wait for one to finish, or see your plan’s limit with squiggle license.
For problems that don’t produce an error code, see Troubleshooting.