Troubleshooting
Resolve common installation, data, specification, rendering, template, 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.
Template problems
| Problem | Likely cause | Resolution |
|---|---|---|
| Template validation fails | The file is raw Vega JSON, damaged, edited incorrectly, or from an unsupported metadata shape. | Return to the source visual and generate a new Studio template, or correct the template metadata. |
| No field can be assigned | Required fields are missing from the Values well or have incompatible types. | Add suitable columns or measures, then reopen or refresh the assignment workflow. |
| Imported visual renders differently | The destination fields have different units, grain, categories, formats, filters, or row counts. | Review every assignment and adapt the specification to the destination model. |
| Download is disabled | The Power BI tenant or host has disabled downloading content from custom visuals. | Use the template Copy action and save the JSON in an approved application. |
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 in template metadata. 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, interactions, and template export before adopting the updated result.