Testing & troubleshooting

Name: Herald
Author: IVG Design

Testing without a window#

A check loads the component in the same view a banner uses, with no window, and reports what it found. Use it to confirm that the file loads, that your input names are right and that a click runs the action you expect. Nothing is shown, stored or executed.

The check is POST /v1/rive/check, also available as the MCP tool rive_check. You send the app and the component. Optionally you send sample field values, and pointer steps to run in order: hoverIn, pressDown, pressUp and hoverOut.

shell

curl -s -X POST "$HERALD/v1/rive/check" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot",
       "component": {"type": "rive", "asset": "bell", "stateMachine": "Main",
                     "inputBindings": {"count": "{count}", "hover": "hover"},
                     "actionRef": "markRead"},
       "fields": {"count": 3},
       "simulate": ["hoverIn", "pressDown", "pressUp", "hoverOut"]}'

JSON

{"loaded": true,
 "inputs": {"count": "number", "hover": "bool"},
 "applied": {"count": "3.0"},
 "artboards": [{"name": "Bell", "width": 64, "height": 64, "defaultMachine": "Main",
                "machines": [{"name": "Main", "inputs": [{"name": "count", "kind": "number"},
                                                         {"name": "hover", "kind": "bool"}]}],
                "animations": []}],
 "takesClicks": true,
 "pointerWrites": {"hover": "false"},
 "clickedActions": ["markRead"]}

How to read the reply:

loaded is true when the animation plays. Otherwise error holds the placeholder text from the table above.
inputs lists the inputs Herald found, by name and kind. Compare it with your inputBindings keys.
applied shows the values your fields wrote. An input missing here received nothing.
takesClicks is true when the animation captures clicks instead of passing them to the banner.
clickedActions names the actions a simulated press and release would run. The action is reported, not run.

The Designer snapshot draws the Designer offscreen, and Rive cells are stand-ins there too. To see the real animation, send a test banner with send_test or herald notify.

When the file is missing or broken#

The component never throws and never crashes the banner. When it cannot play the file, it draws a dashed rounded box with a warning icon and the reason, and shows the same reason as a tooltip. The rest of the banner is unaffected. Use this table to read the message.

Text in the placeholder	Cause	Fix
`the Rive component has no asset or path`	Neither `asset` nor `path` is set.	Set one of them.
`asset "bell" is not declared by the manifest and is not installed`	The manifest has no asset `bell` and `<app>/bell.riv` does not exist.	Save the manifest with the asset, or upload the file.
`file not found: <path>`	The path does not exist.	Fix the path, or copy the file into the app's folder.
`"x.riv" is not a .riv file`	The extension is wrong.	Use a file that ends in `.riv`.
`"x.riv" is not a regular file`	The path is a folder or another kind of item.	Point at the file.
`"x.riv" is empty`	The file has no bytes.	Export it again from Rive.
`"x.riv" is 12 MB; Rive assets are limited to 10 MB`	The file is too big.	Make the animation smaller.
`remote assets are not supported: https://...`	The path is a URL.	Download the file and reference it.
`a relative asset path cannot leave the app's assets folder`	The path contains `..`.	Use a name inside the folder.
`asset type "x" is not supported (only rive)`	The manifest asset's `type` is not `rive`.	Set `"type": "rive"`.
`an app can have at most 32 animation assets`	The folder holds 32 files.	Remove files you do not use.
`could not copy the asset: ...`	The copy into the folder failed.	Check the source file and the disk.
`no artboard "X" (available: ...)`	The artboard name is wrong.	Use one of the listed names.
`no state machine "X" (available: ...)`	The state machine name is wrong.	Use one of the listed names.
`the file has no state machine or animation`	The artboard is empty.	Add a state machine or an animation.
A message from the Rive runtime.	The file is not a valid or supported `.riv`.	Export it again with a runtime-compatible editor.

Herald prints names in these messages with curly quotes. A static preview from POST /v1/preview or the MCP tool render_preview also draws a dashed box with the asset name for a working Rive component. That box is a stand-in, not an error, because previews cannot draw Rive.

Troubleshooting#

Start with a check: its loaded, inputs and applied answer most of these.

Symptom	Likely cause	What to do
A dashed box with a message.	The file did not load.	Read the message in the table above and run a check.
The animation plays but never reacts to fields.	The input name has the wrong case, or is not an input of that state machine.	Compare the check's `inputs` with your keys. A wrong name is skipped silently.
It reacts to the first notification only.	The same value was written again, and unchanged values are not written.	A trigger fires when the value changes. Send a different value, or bind a counter.
A trigger fires when the banner appears.	The bound field is truthy at load.	This is expected. Bind a field that is absent on the first notification, or use a Boolean.
An input keeps its old value when a field disappears.	An absent token leaves the input alone.	Send an explicit `0` or `false`, or bind a field that is always sent.
Hover does nothing.	No input is bound to `hover`, or the input name differs from the key.	Write `"<input name>": "hover"`. The key is the input name and the value is the keyword.
Hover works but a Rive pointer-enter listener does not.	Pointer move is not passed to Rive.	Use the `hover` input.
Clicking the animation opens the notification instead of running the action.	There is no `action` or `actionRef`, or the action id is hidden.	Add one and check that `takesClicks` is `true`.
The animation looks letterboxed.	The box has another ratio than the artboard.	Leave out `aspectRatio`, set it to the artboard's ratio, or resize the artboard.
It is too small or cut off.	A fixed row is smaller than the box, or `height` is larger than the row.	Use an `auto` row or a smaller `height`.
It works in the Designer but not after export and import.	The template uses an absolute `path`.	Use `asset` ids or a relative `path`. Export rewrites loose paths.
`render_preview` shows a stand-in.	Offscreen renders cannot draw Rive.	Use `send_test` or a check.
The banner is slow to appear.	The file is large, or hosted assets are being fetched.	Make the file smaller and embed its assets.
The manifest saved but the animation is missing.	The asset path is unreadable or over 10 MB.	Fix the file and save the manifest again. Herald's log names the asset and the reason.
A replaced file is not picked up.	The bytes did not change, or the template uses a `path` to a copy.	Save the manifest again. An `asset` reference installs again when the source changed.

Edit this page on GitHub