Forward Insight errors

This page covers what goes wrong when you attach a study to the chart as a Forward Insight, and what goes wrong when you click an event afterwards. Each message is quoted as the app shows it, with its cause and fix.

How attaching works

Open a finished study run and click Attach to chart. The wizard has four steps:

What do you care about? Pick one result the study already measures.
Break down by. Pick the dimensions that split events into cohorts, such as session or direction. Pick none for one global card. Click Apply breakdown.
Applying your breakdown. The Agent adds a pin_cell result to the study, saves it, re-runs the study and builds the chart card. It tries up to three times.
Pin name. Check the preview, name it, and click Save pin.

Nothing reaches your chart until Save pin succeeds.

Step 1: What do you care about?

Message	Cause	Fix
"This study doesn't publish a metric that can go on the chart yet."	The study declares no `metric` result.	Add `results.declare({ id, kind: "metric", title, description })`, publish it in `onFinish`, run the study, and attach again.
"Couldn't read this study."	The study's files did not load.	Click Try again.

Step 2: Break down by

Message	Cause	Fix
"… doesn't capture any dimensions, so there is nothing to break … down by. It pins as one global card."	The study declares no dimensions.	Continue for one overall number, or ask the Agent to rebuild the study with dimensions such as session, direction or volatility regime.
"… captures dimensions, but it doesn't measure … per cohort"	The dimensions exist, but the result you picked is not published per cohort.	Continue with a global card, or have the study publish that result indexed by the dimensions.

A global card shows the same reading on every matching event. When the events differ in a way that matters, such as London against New York, a global number can hide one cohort that works and one that does not.

Step 3: Applying your breakdown

Failures here say "Nothing was saved to your chart." You can go back and change the breakdown, or cancel.

Message	Cause	Fix
"The agent couldn't produce a study edit for this selection."	The Agent returned no change.	Go back and pick fewer dimensions, or a different result.
"The agent proposed the same study edit again …"	The second attempt repeated the first.	Change the breakdown. Retrying the same one gives the same result.
"Attempt 2 was blocked by exactly the same problem as the one before it … The blocker: …"	One problem survived two attempts.	Read the blocker. It is usually a study problem from the table below.
"We stopped after several attempts without a working breakdown."	Three attempts failed.	Fix the study with the Agent, then attach again.
"The study ran and the pin bound, but the preview came back empty"	The re-run produced no cohort rows.	Check the run over history has events for this range, then attach again.

The blockers the Agent works from come from the study itself:

Blocker	Cause	Fix in the study
`pin_cell kind must be popover_layout`	The pin result was declared as a table.	`results.declare({ id: "pin_cell", kind: "popover_layout", indexedBy: [...] })`.
`pin_cell has 3 rows for scope [direction]; need exactly one row per scope tuple`	Two rows share the same dimension values.	Publish one cell per combination of scope values.
`pin_cell has 2 rows with no scope dimensions; need exactly one row`	A global card with several rows.	Publish one row.
"study does not group its events: it exports no scope(ctx)"	The study has no `scope(ctx)`.	Export `scope(ctx)` returning the event's scope tuple.
"this run grouped no events at all — scope(ctx) returned null or failed for every event. Return { direction } from scope() for the events the pin shows."	`scope` left every event out.	Return the tuple for the events the Forward Insight covers, and check the run's scope errors.
"this run grouped 40 event(s), but every group was provisional — the data each event needed was not ready when its group was decided …"	The events had incomplete data when `scope` ran. This is not a study bug.	Run over a range where the events have complete data.
"this run scoped 40 event(s) on [session], but the pin is indexed by [direction] — no marker carries direction. …"	The pin is indexed by a dimension `scope` never returns.	Return it from `scope`, or pick dimensions `scope` already returns.
"this run scoped 40 event(s) and records [session, direction], but no single event carried all of [session, direction] together. …"	The dimensions were set on different events.	Return them all in one tuple from `scope`.
"the study's scope tuple does not set every scope dimension: direction"	A declared scope dimension is missing from the tuple.	Return it on every path, or declare it `role: "report"` if it is an outcome.
"study puts report-only dimensions in the event's scope tuple: outcome"	An outcome dimension is in the tuple.	Keep outcomes as `role: "report"`: measure them in `onEvent` and publish them through `indexedBy`.
`dimension "x" value "Strong trending" is not canonical`	A scope value is a display label.	Use the declared value, such as `"strong_trending"`.

Step 4: Save pin

Message	Cause	Fix
"Could not save pin"	The save request failed. The toast gives the reason.	Click Save pin again. If it fails the same way, close the wizard and attach again.
"Pin saved to chart"	Success.	Click an event on the chart.

What the study needs

A study attaches cleanly when:

The study exports scope(ctx), which returns every scope dimension from what was known when the event fired. Each marker on the chart lands in the cell scope returned for it, the same call the study's run made, so live markers agree with the study's counts.
Outcomes, such as which target was hit, are dimensions declared with role: "report". A dimension with no role is a scope dimension.
Scope values are the dimension's declared values, never labels.
The study measures something after the event, such as ctx.candles.forward(...) or a later event from ctx.flows.<as>.events({ after }).
Percent metrics set their scale, so 53% does not show as 5300% or 0.53%.
Every count n is true: build cells with ctx.groupByScope(rows). Small cohorts are allowed and show a limited-sample note.

dimensions.declare({ id: "direction", title: "Direction", description: "Break direction", values: ["up", "down"] });
dimensions.declare({ id: "outcome", title: "Outcome", description: "Which side was hit first", role: "report" });

export function scope(ctx) {
  if (ctx.event.flow !== "orb") return null;
  return { direction: ctx.event.payload.side === "long" ? "up" : "down" };
}

export function onEvent(ctx, scope) {
  const path = ctx.candles.forward({ bars: 12 });
  // measure the outcome from path, then ctx.collect it
}

After it is attached

Click an event on the chart to open its Forward Insight. These are the popover's states:

Message	Cause	Fix
No study pin on this chart yet	Nothing is attached for this definition on this chart.	Click Go to Studies and attach a study run.
Not set up for this profile	The Forward Insight was saved under another profile than the chart's definition uses, or one of them has no profile.	Click Switch to the named profile, or attach a study run made under the chart's profile.
Can't use this pin on 5m	It was saved for another timeframe.	Switch the chart to that timeframe, pick another Forward Insight, or click Pin a 5m study.
Checking cohort…	Chartnaut is matching the event to a cohort.	Wait.
No study insight for this event	The study's `scope` returns `null` for events like this one.	Click Run a study and build one whose `scope` returns a tuple for them.
This insight can be wrong on live events	The study has no `scope(ctx)`: it groups events with `ctx.scopeEvent` inside `onEvent`, where reads after the event can decide the group.	Click Update to have the study builder's agent move the grouping into `scope(ctx)`.
Need more chart history	The study needs more bars or indicator data to place this event.	Scroll back or wait for data, then click again.
Could not check cohort: "Forward Insight is missing frozen study source"	It was saved without its study source.	Attach the study run again.
Could not check cohort: "Study script is not loaded"	The study code has not loaded in this session.	Open the study in the builder once, then click again.
Could not check cohort: "Cohort probe failed."	Matching the event failed.	Click the event again.
Could not load pin results: "No record marker for this event."	The study has no group for this event.	Return a tuple from `scope` for every event you want a Forward Insight on.
Could not load pin results: "Contextual popover produced no lines for this marker."	No `pin_cell` row matches this event's dimensions.	Publish a cell for every combination of scope values.
No insight available	No results snapshot exists for this Forward Insight.	Click Go to Studies and attach the run again.

A Forward Insight shows what happened after past events in the same cohort. It does not measure the event you clicked.

More on the study side: Show studies on charts. On the chart: Forward Insights on the chart.

PreviousEmit not collected NextDefinition events