Validation

Gricea has a multi-layered validation system that checks your study design in real-time as you work in the visual builder. The validation panel shows errors, warnings, and suggestions to help you build a correct study.

The validation runs automatically and checks three levels:

1. Structural validation — Is the flow graph well-formed?
2. Node configuration validation — Is each node correctly configured?
3. Runnability validation — Can the study actually execute from start to end?

You must fix all errors (red) before publishing. Warnings (yellow) are recommended fixes. Info (blue) items are suggestions.

These rules ensure your study flow graph is well-formed:

Must have at least one node — An empty flow cannot be published. Add at least one node to your canvas.

Must have exactly one start node — There must be exactly one entry point — a node with no incoming connections. If you have zero start nodes or multiple disconnected start points, the study cannot determine where to begin.

No orphan nodes — Every node must be connected to the flow. If a node has no incoming AND no outgoing connections, it's an orphan. Either connect it to the flow or remove it.

No dead-end nodes — Every node (except the final End node) must have at least one outgoing connection. If a participant reaches a dead-end node, the study cannot proceed.

No cycles in study flows — Study-level flows must not contain infinite loops. (Task-level flows can have loops via the Loop node.) Cycles are detected using depth-first search and flagged as errors.

Different node types have different connection patterns:

Regular nodes (Survey, Instructions, Task, Set Variable, Logic) — Have one outgoing connection to the next node. Drag from the bottom handle to the top handle of the next node.

Branch nodes — Have multiple outgoing connections: one for each branch condition plus a default path. Each branch handle appears at the bottom of the node labeled #1, #2, etc. The "default" handle handles all cases that don't match any condition. You must connect the default handle — this is a common error.

Randomize nodes — Have a single outgoing connection. The randomize node sets variables but doesn't branch the flow — use a Branch node after Randomize to route participants based on their assigned condition.

Loop nodes (task-level only) — Have two types of connections:

• The loop body connection goes to the first node inside the loop
• The exit connection goes to the node after the loop
• Loop End nodes inside the loop body automatically connect back to the loop

Within-Subject blocks — The Start node connects to the first node in the condition block. The End node loops back to the Start until all conditions are completed. Make sure there's at least one view node (survey, task, or instructions) between Start and End.

End node — The special End node terminates the study. Connect the last node in your flow to End.

Each node type has specific configuration requirements:

Survey nodes (study:survey, task:inline-survey)

• Must have at least 1 question (error if empty)
• Questions should have variableName set to save responses (warning if missing)

Task nodes (study:task)

• Must have an embedded task definition or task reference (error if neither)
• Required study variables must be bound to the task (error if missing bindings)

Branch nodes (study:branch, task:branch)

• Must have at least 1 branch condition (error if empty)
• All branches must be complete — each needs a variable, operator, and target node (error if incomplete)
• Must have a default path connected (error if missing)

Randomize nodes (study:randomize, task:randomize)

• Must have conditions or variables defined (error if empty)
• For within-subject randomize: must have a loop-back path through at least one view node

Loop nodes (task:loop)

• Must specify a loop body (first node in the loop) — error if missing
• minTurns cannot exceed maxIterations — error if invalid

Await-user-input (task:await-user-input)

• Must specify sourceInstanceId (which component to wait for) — error if missing

LLM nodes (task:llm-call, task:llm-stream)

• Should have at least a systemPrompt or userPrompt (warning if both empty)

RAG nodes (task:retrieve-context)

• Should have a query configured (queryVariable or queryTemplate) — warning if missing

Beyond structural and configuration checks, Gricea performs deeper analysis to ensure your study can actually run:

Undefined variables — If a node references a variable (e.g., in a branch condition or template) that is never set by any upstream node, you'll get an error. Make sure variables are defined (via Set Variable, Randomize, or Survey) before they're used.

No path to end — Every node reachable from the start must have at least one path that eventually reaches the End node. If a node can be reached but has no way to get to End, participants could get stuck.

Invalid goto targets — If a node references another node that doesn't exist (e.g., after deleting a node), you'll get an error. Reconnect the broken link.

Invalid branch/default targets — Branch conditions that point to non-existent nodes are flagged. Check that all branch connections are still valid after rearranging your flow.

Logic expression errors — Invalid expressions in Logic nodes (syntax errors, missing variables) are caught and reported with details.

Here are the most common issues researchers encounter when building studies:

Forgetting the default branch path — Every Branch node needs a "default" connection for cases that don't match any condition. If you only connect the named branches, participants whose variables don't match will have nowhere to go.

Fix: Connect the "default" handle at the bottom of the Branch node to a target node.

Disconnected nodes after rearranging — When you move or delete nodes, connections can break. Check for orphan or dead-end warnings.

Fix: Use the Validate button to see all issues. Click on an error to select the problematic node.

Using a variable before it's set — If you branch on user_stance but the survey that sets it is downstream, the variable will be undefined.

Fix: Ensure Set Variable, Randomize, or Survey nodes that define variables come before nodes that use them in the flow.

Loop without proper stop conditions — A loop with no stop condition will run indefinitely (up to the safety limit). Always set at least one stop condition.

Fix: Add stop conditions like maxIterations, userAction: clickStop, or timeElapsed.

Within-subject block without a view node — The within-subject block needs at least one "view" node (survey, instructions, or task) between Start and End so there's something for participants to actually experience.

Fix: Add a survey, instructions, or task node between Within Subject Start and End.

Randomize without a downstream Branch — The Randomize node sets variables but doesn't split the flow. You need a Branch node after it to actually route participants to different experiences.

Fix: Add a Branch node after Randomize that checks the assigned variable.