Troubleshooting
Resolve common installation, data, specification, rendering, reuse, interaction, and performance problems in a consistent order.
Installation and access
| Problem | Checks and resolution |
|---|---|
| The visual is not found in Marketplace | Confirm the full name, update Power BI Desktop, sign in, and ask your tenant administrator whether marketplace visuals are restricted. |
| The Add action is unavailable | Check report edit permission, tenant policy, and whether your organisation requires an administrator-approved organisational visual. |
| The editor will not open | Select the visual, confirm it is not in read-only mode, and use the supported Edit or advanced-edit action in Power BI Desktop. |
Blank or incorrect preview
- 1
Check Diagnostics
Fix specification or configuration parse errors first.
- 2
Check Data table
Confirm
datasetcontains rows and exact field names. - 3
Check the selected dataset
Verify every mark reads from the intended source or derived dataset.
- 4
Check scale domains and ranges
A valid mark can still render outside the viewport or at zero size.
- 5
Check opacity, fill, stroke, and clipping
Temporarily use obvious colors and fixed sizes to isolate styling problems.
- 6
Check renderer and viewport
Try SVG, 100% zoom, visible boundary, and scrollbars to expose overflow or Canvas-specific behavior.
Problems with a reused specification
| Problem | Likely cause | Resolution |
|---|---|---|
| The pasted JSON will not parse | The copy is incomplete, was pasted alongside existing content, or contains commentary from the source page. | Select the entire Spec editor contents, paste the specification over them again, and check Diagnostics for the reported position. |
| The visual renders but shows no data | The specification references field names that do not exist in this report. | Compare the references against the Data table and correct either the field names in the model or the references in the specification. |
| Nothing can be assigned to the visual | The columns and measures the specification expects are missing from the Values well or have incompatible types. | Add suitable columns or measures, then apply the specification again. |
| The same specification renders differently here | The destination fields have different units, grain, categories, formats, filters, or row counts. | Review each field, then adapt the specification to the destination model. |
Performance problems
- Reduce the number of rows sent to the visual with model aggregation, report filters, or a more appropriate grain.
- Avoid repeated expensive transforms when a derived dataset can be reused by multiple marks.
- Use Canvas for dense mark sets and compare performance with SVG using realistic interactions.
- Disable live preview while making large structural edits.
- Limit the number of simultaneously animated marks and high-frequency signal updates.
- Inspect derived datasets for accidental Cartesian expansions or duplicate rows.
- Test performance in Power BI Service as well as Desktop when the report will be published.
Version-change messages
The Studio records its build and the Vega provider version alongside the applied specification. When a specification was authored with a different version, the Studio can present a version-change message. Review the change context, make a backup, then test parsing, rendering, and interactions before adopting the updated result.