Troubleshooting custom visuals

A custom visual draws in a sandbox beside the report, so when something goes wrong the tile carries the message itself. Find yours below; for how custom visuals work, see Custom visuals and the visual library, and for messages from the rest of DataPrism, Troubleshooting.

How a custom visual reaches a tile

The report opens with the visual's saved definition: its code, its libraries, its data roles and its options.
DataPrism checks the definition before it runs: custom visuals enabled for the deployment, this tile not switched off, the code matching the signature it was saved with, and a supported sandbox version.
When the checks pass, the visual's sandbox starts. A report page runs about eight custom-visual frames at once, so on a busy page the remaining tiles wait for a free slot.
If a check fails, or the sandbox cannot start, the tile shows a placeholder, stops with a message, or records a reason you can read in Diagnostics.

What a placeholder means

A placeholder replaces the visual's drawing and shows the reason as its message. Find yours in the table:

The tile says	What it means	What to do
This visual has no code yet	The tile has no saved custom code.	Choose Open studio and write it.
Custom visuals are disabled on this deployment	Custom visuals are switched off for the whole deployment.	Ask an administrator to enable them.
Custom visuals are disabled on this deployment - edge policy missing	The check that serves the sandbox cannot be made, so custom visuals stay off.	Tell your administrator that the edge policy is missing.
Checking the sandbox edge policy	DataPrism is still checking whether the sandbox may start.	Wait; the tile starts, or shows another message.
Disabled by an administrator	Someone with the disable permission switched this visual off, on this tile or everywhere.	On a tile, an author saves the visual again. Everywhere, someone with the permission chooses Enable in the visual library.
This visual was not rendered: its code does not match the saved signature	The code no longer matches the signature recorded when the visual was saved, so the sandbox refuses to run it.	Open the Studio, apply the code again and save the report to record a fresh signature.
This visual was not rendered: it was saved without a code signature	The code has no signature to check.	Open the Studio and apply the code again; saving it records a signature.
This visual targets a retired SDK version	The visual was saved for a version of the sandbox that is no longer used.	Open the Studio and apply the code again to save it against the current version.
Custom visuals cannot render on this surface	This surface does not run custom visuals.	Open the report on its normal page.
Saved by a newer version of DataPrism - reload to view	The report was saved with a newer version of DataPrism than this browser tab has.	Reload the page.

Note

The signature is DataPrism's fingerprint of the visual's code, its libraries and its sandbox version, recorded when the visual was saved. A tile stops rather than run code it cannot verify, which is why editing code outside the Studio leads to a placeholder.

When a visual stops responding

A visual that stops sending anything while it should be working is stopped, and the tile reads This visual stopped responding.
Choose Restart to start it again. Restarts are limited: after three stops the tile reads This visual stopped responding three times and was turned off for this session, and no Restart button is shown.
The reason line records what the sandbox saw, in wording such as:
- no message from the frame for 30 s (budget 30 s; last status ready, 1 capture(s) in flight): nothing arrived from a visual that had been working. The sentence notes how long it was silent, the window it was allowed, and what it was doing last.
- the sandbox guard did not report ready within 45 s: the sandbox itself did not come up in time.
- the sandbox frame reloaded unexpectedly: the frame reloaded on its own, which counts as a failure.
- the visual did not call uni.ready() within 45000 ms: a finding from the last run; the code never signalled that it was ready to draw. The readiness call is described in Sandbox, network and the allowlist.
These sentences record the window each check allowed: roughly half a minute of silence for a working visual, and about 45 seconds for the sandbox to come up.
A stop means the sandbox stopped hearing from the visual. Read the tile's Diagnostics for the last runtime report, fix the code in the Studio, apply it and save the report. Reload the page for a fresh session before you try again.

When a click or an export is refused

A click that would filter the report is checked against the visual's fields and its rows. If it names a field that cannot be filtered, or a value that is not in the rows delivered to the visual, the click does nothing and the refusal is recorded as select rejected: field is not a filterable dimension or value is not in the delivered rows.
When a visual exports a picture, the sandbox checks the image before it is used. A refused image reads snapshot with the reason: snapshot not-png, snapshot bad-header, snapshot too-large, snapshot blank or snapshot undecodable. snapshot blank means every sampled pixel was the same, so nothing was drawn; snapshot too-large means the image was larger than the cap.
Links and embeds follow their own allowlist rules and have their own refusals; see Sandbox, network and the allowlist.

Questions, answered

Why does my tile say "This visual has no code yet"?

The tile has no saved custom code, so there is nothing to draw. Choose Open studio and write it; writing custom visual code needs edit access to the report and the authoring permission, described in Who can do what in DataPrism.

Why does my tile say "This visual was not rendered: its code does not match the saved signature"?

The code no longer matches the signature recorded when it was saved, usually because it was edited outside the Studio. Open the Studio, apply the code again and save the report so the new code is signed.

Why does my tile say "This visual was not rendered: it was saved without a code signature"?

The tile's code has no signature to check, so the sandbox refuses it. Open the Studio and apply the code again; saving the report records a signature.

Why does my tile say "Disabled by an administrator"?

Someone with the disable permission switched the visual off: on this tile, or everywhere at once. On a tile, an author saves the visual again. If it was switched off everywhere, someone with the same permission chooses Enable in the visual library.

Why does my tile say "Custom visuals are disabled on this deployment"?

Custom visuals are switched off for your whole deployment, so no custom visual runs anywhere. Ask an administrator to enable them. The longer variant that adds "edge policy missing" means the sandbox could not be served, which is also for your administrator.

Why does my tile say "Saved by a newer version of DataPrism - reload to view"?

The report was saved with a newer version than your browser tab has, so the tab cannot draw this tile safely. Reload the page to pick up the newer version.

Why did my visual stop responding?

The sandbox stopped hearing from the visual, so it stopped the frame and put This visual stopped responding on the tile. Look at the tile's Diagnostics, fix the code in the Studio, apply it and save the report. Choose Restart if you just want to try it again.

Why is there no Restart button on my stopped visual?

Restarts are limited. After three stops the tile is turned off for the session and reads This visual stopped responding three times and was turned off for this session. Reload the page for a fresh session, and fix the code so it does not stop again.

Why do some custom visuals wait before they run?

A report page runs about eight custom-visual frames at once. On a page with more, the extra tiles wait for a free slot and start as you move around the report. This is normal and needs no action.

Why did my click inside the visual not filter the report?

The click has to name a field that can be filtered and a value that is in the rows the visual was given; anything else is refused, and the reason reads select rejected: field is not a filterable dimension or value is not in the delivered rows. Check the field and value the code selects.

Why was an exported picture refused?

The sandbox checks each picture a visual exports. An image that is not a PNG, is malformed, is larger than the cap, is blank, or cannot be decoded is refused, with the reason after snapshot, such as snapshot blank. Check that the visual draws something before it exports.