Execution, errors, and limits

Use Preview before publishing JavaScript. A syntax message under the editor catches code that cannot be parsed; it does not prove the code will run successfully with participant inputs.

What runs together

All calculations in one JavaScript Flow step start together. They read the same values from when that step began, including reads after await. Writes do not change those inputs.

A following Flow step runs after all calculations finish and their results save. Put a dependent calculation in a following step. Keep calculations short: synchronous JavaScript runs on the browser’s event loop and can freeze the page if it never finishes.

Writes are applied in calculation order. Later writes to the same result or global key replace earlier writes; globals.init preserves existing keys. A named calculation’s returned result is written after its explicit setter calls. An unnamed calculation ignores its return value and saves Flow outputs only through variables.set. Use distinct output names so readers do not need to reason about competing writes.

When a calculation fails

If any calculation throws, rejects, writes an invalid Flow value, returns an invalid named result, or exceeds a limit, none of that Flow step’s result or global-data changes save. Preview identifies the calculation and error. Check:

1. Does every named calculation return the selected type, and does each variables.set value match its declared Flow type?
2. Are input names declared and spelled correctly, including capitalization?
3. Could a known input be null because its step or question was skipped?
4. Are any names shared by a URL parameter, a study value, and a Flow result?
5. Does the code try to read a result that another calculation in the same step has not saved yet?

Participant execution makes up to three automatic attempts per retry cycle. After those fail, Retry starts another cycle. Interrupted attempts can also run again. Fix and test code before publishing; retrying a programming error will not fix it.

In the published survey, the participant sees a general calculation-failure message and Retry. They cannot continue past a failing step. Preview gives the researcher the calculation number, error name, and message; reproduce the failing inputs there to diagnose it. Published code is fixed to its version, so a code correction requires a new publication. When reusing the URL, sessions with saved answers keep their original version unless the owner resets older sessions, which discards their progress.

Question-script failures block normal navigation rather than continuing with missing saves. Data writes already acknowledged by a question script or setup are not undone by a later failure.

Network requests and Preview

You can use await for asynchronous work. Browser restrictions such as cross-origin request rules still apply.

External requests and other external actions can run again on retries, reload, or revisits. They are not undone if a calculation fails. Use an external service’s duplicate-request protection when repeating an action would cause harm. Never put secret API credentials in survey JavaScript: participants can inspect browser code.

Preview uses separate in-memory results and JavaScript data; it does not create a participant response. Requests to external services in your code still execute. Use test services or test inputs during Preview.

Result types and names

null, undefined, arrays, and objects are invalid named calculation results and Flow variable values. An unnamed calculation ignores its return value, regardless of Result contains. Use saved JSON data for objects or arrays.

Leave Save result as empty for an unnamed calculation. Otherwise, names start with an English letter and contain at most 64 English letters, digits, or underscores. Names are case-sensitive. fpscanner is reserved for the browser scanner. Reusing a Flow result name updates that value; every declaration must keep the same type.

Incomplete calculations can remain in a draft. Publishing requires at least one calculation in every JavaScript step, with code in each calculation. A complete calculation beside one without code does not make the step publishable. Preview is still needed to check named results and variable writes against their declared types at runtime.

Size limits

KiB means 1,024 bytes; MiB means 1,048,576 bytes. Avoid saving large raw datasets in a participant response. Keep only the values needed to reproduce and analyze the study.