Diagnosing Simulation Errors and Warnings

The Scenario Diagnostics tab tells you whether a scenario is healthy — cycles, unresolved references, runtime warnings, authoring errors all in one place.

When a formula doesn't compute the way you expect, an act method misbehaves, or you've accidentally created a circular dependency, the Scenario Diagnostics is where you go. It's a single tab that answers the question "is this scenario healthy?".

Where to find it

Select a Scenario in the Model Navigator
Open the Properties Panel
Switch to the Diagnostics tab

The tab is empty when everything is fine. As issues appear, they're grouped into sections so you can fix them one category at a time.

What you'll see

Cycles. Circular formula references — org.team_cost → team_a.cost → team_a.personnel_cost → org.team_cost. Each row shows the chain so you can follow the loop and decide where to break it. Common cause: two properties that read each other's current value. Common fix: use agent.get_prop("x", -1) on one side to read the previous timestep instead.

Unknown names. A property or relationship name the engine can't find on the agents it was handed — a typo, a renamed property, a deleted relationship type. These matter because the aggregation doesn't fail, it silently contributes 0, so the value downstream looks plausible. The diagnostic names what was asked for and what was available.

Invalid offsets. A get_connected(agent, "rel", offset) whose offset isn't a finite number ≤ 0 — typically a lag parameter that has flipped sign, or an expression that divided by zero and became infinite. The call returns nothing rather than reinterpreting the offset, because both alternatives (reading the future, or silently reading the current step) produce a full, confident, wrong series.

Unresolved dynamic references. A formula whose get_connected offset is an expression the engine can't resolve ahead of time (arithmetic, a conditional). The results are correct, but the engine has to build each agent's whole history to get them, and that cost grows with the square of the number of timesteps. Treat this as a performance warning: move the offset into its own property and reference that property. See Reading Connected Agents in Rhai.

Runtime warnings. Errors that happened during the most recent simulation run: divide by zero, NaN or infinity, type mismatches. Each warning lists the agent, the timestep, and the formula or act method that produced it.

Authoring errors. Syntax errors and unknown name references in your formulas and act methods, aggregated so you can see every broken script in one place.

A useful workflow

Cycles first. They cause every dependent property to fall back to baseline values, masking other problems. Break the cycle and rerun.
Authoring errors next. Anything broken at parse time needs to be fixed before runtime warnings can be trusted.
Then runtime warnings, unknown names, and invalid offsets. Once formulas compile cleanly, these are usually localized and easy to track down — and each one is a value that is quietly 0 or missing.
Performance warnings last. "Unresolved dynamic references" doesn't make results wrong; fix it when a run feels slow.

Tips

A scenario can be partially healthy. Sections are independent, so you can ship a working part of the simulation while you work on a problematic part.
The diagnostics tab only shows issues for the currently selected scenario. If you have multiple scenarios with different overrides, switch to each one in turn.
A run that comes back empty is itself a signal: check this tab before suspecting the connection — a scenario with no agents, or one whose only formula fails to compile, has nothing to return.

Next steps

Writing Property Formulas — getting formulas right the first time
Writing Act Methods — when single-property formulas aren't enough
Reading Connected Agents in Rhai — graph traversal patterns