Skip to main content
Showing results for 
Search instead for 
Did you mean: 

Find everything you need to get certified on Fabric—skills challenges, live sessions, exam prep, role guidance, and more. Get started

Power BI Team
Power BI Team

Custom Visuals Sandbox is coming - Here's what you need to know

Custom visual authors and users - we'd like you help to find the last bugs in a new feature for custom visuals - sandboxing.  We've seen a lot of great visuals be created by our community, and we've seen how some of those visual interact with each other, with our own UI elements, and with our APIs.  This has led to some glitches for users and visual authors. So we're planning to add sandboxing.  Sandboxing will be enabled in the service on or after March 22nd 2016.  


Asks and Acitons for custom visuals users/developers 

  1. Test your visuals using the steps shown below
  2. Review the list of Known Issues.
  3. Reply to this post with issues you find so we can investigate them.



What is sandboxing for custom visuals

Sandboxing provides a layer of isolation for each custom visual by hosting it in a dedicated iFrame.  Your code and dependencies are injected dynamically into the iFrame.  It ensures you don’t have conflicts with other visuals/elements on your page and removes access to APIs that you shouldn’t be using in your custom visuals.


When will Sandboxing be enabled for custom visuals?

We expect it to enabled sandboxing on or around March 22nd 2016. We’ll adjust this based on your feedback and reported issues.


What is the impact on my custom visual?

Sandboxing runs your visual’s code in a low privilege iFrame with no domain.  You will not be able to assume access to Power BI styles (CSS), Power BI fonts, or undocumented Power BI APIs.  We will inject all the required interfaces into the iFrame including your visual’s code.  Then we will marshal data points and required settings across the iFrame boundary.  Since the iFrame has no domain, you will not have access to cookies or local storage. Lastly, how you debug your custom visual will change a little, which I’ll cover below.

Here’s an example iFrame that your visual would be loaded into:

<iframe class="visual-sandbox" src="/sandbox?plugin= MyVisualName" style="width: 1177px; height: 682.04px;" sandbox="allow-scripts"></iframe>


How can I test my visual in the Sandbox?

Starting now you can test your visuals, dashboards, and reports in the sandbox by adding the following flag to the URL in the address bar.

Follow these steps:

  • Sign-in to your Power BI account
  • Paste the following URL into your browser address bar


  • Press enter to navigate to the URL above
  • You know the feature switch successfully applied if after the browser loads the flag is in the URL. For example:


  • Please note that if you needed to sign-in in step #2, the feature switch will not be applied. You can click the URL again, or just paste ?sandboxVisualsEnabled=1 on the URL and refresh.


How do I debug in the sandbox?

To debug, the easiest way is to add the following line of code to your visual’s init method or wherever you’d like a breakpoint for the browser’s debugger.




Then, when you’d like to debug your visual, launch the browser’s debugger, add your visual to the page and bind some data to it.  The debugger will automatically break when init is called by Power BI allowing you to see your code.  Without this, you may find it hard to identify where the code is located in the browser’s debugger since it is dynamically injected into the iFrame.


A note about unhandled exceptions

One thing that is important for you to add to your visuals is some hardening for unhandled exceptions. To keep the iframe and the host page in sync, we run synchronization code in the iFrame alongside your visual’s code.  If your visual throws an unhandled exception, we attempt to catch it so our synchronization code keeps working. Even then, your code might not work in the resulting state. We’ve found that some custom visuals have unpredictable behaviors after they throw an unhandled exception. Unfortunately, since it’s your code we’re not able to fix those issues on our side. The most common symptom of this is the visual stops resizing correctly when the user resizes the visual in Power BI.  If you see this happening, check if the custom visual is throwing exceptions and resolve those before submitting an issue.


Known issues

Here's a list of known bugs we're tracking:

1) Sometimes the visual does not resize in the iFrame.  Usually this is due to an unhandled exception in the visual, but sometmies it's the framework. We're working on a fix. Your code should trap it's exceptions to avoid one of the major causes.

2) Fonts and CSS styles.  Some visuals depend on Fonts and CSS from Power BI.  Not all styles are available within the sandbox.  You will not have access to Power BI's fonts in the iFrame.  Please adjust the code of your visual to use specific and predictable Fonts and CSS.

2) iFrame within custom visuals are blocked.  This is feature is due to the sandbox security policies we set.  You should updated your code not to use an iFrame.

3) Performance for loading custom visuals.  The is an impact due to the sandbox for how fast cusotm visuals load. We are working on fixes to make this better and some features to make it better still. 

Regular Visitor

I have noticed that issue where custom visualization are partially generated OR not generated are occuring only on the pinned custom visuals on dashboard and not on reports.

Also, today it's completely behaving unpredictable and sometime few of the custom viz are not shown on dashboard with errors on console as,

Sandbox plugin

XMLHttpRequest cannot load Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'null' is therefore not allowed access. The response had HTTP status code 404.


Any idea on how to fix it ?

Issue Power BI.png


Regular Visitor


Before sandboxing it was possible to have a custom visual click the “Refresh” button programmatically. This was a very practical yet simple way to bring real-time or near real-time behavior into reports. There is some support for auto-refreshing visuals in dashboards; however it is not as useful as having it in reports since we cannot interact with the content of the visuals in dashboards. It would be nice to have more easy-to-use real-time support in reports, maybe from the custom visuals API or by having access to an official visual that calls for a “refresh” at regular time intervals.



Resolver II
Resolver II

Hello, @bashirs.

I encountered some additional issues caused by the sandboxing, for which I was not able to find suitable workarounds:

  1. IVisual's destroy() method is not invoked when changing the page on the report. I've been using this method to persist properties regarding the state of the visual so that the user can move between pages without having the visual reset. Is there another way I can perform this operation when the page is changed? My current workaround is to persist the state every time the user performs a sequence of state changing operations, but it is a horrible solution because it involves a lot of unnecessary communication with the server and it invokes the update() method every time.
  2. DOM drag events are not functioning properly. More specifically, when a "drag" event occures, it won't stop firing even after the mouse button is released. Also, the "dragend" event never occurs. This causes the dragged element to be dragged indefinitely. My guess is that the window element's events are not captured inside the visual's iframe so elements inside it are not informed when the mouse button is released. My workaround for this issue was- a) Defining a flag that makes the drag event handler to return immediately when set to "false". b) Set the flag to "true" on "dragstart". c) Set the flag to "false" on "mouseup" events for all of the element's ancestors and the window element. The problem with this solution is that the drag event never stops firing, and just won't perform anything when the flag is set to "false". Additionally, while this workaround works better than expected in Firefox and Chrome, it has some annoying issues in IE11 and Edge(Will specify if needed).

I'd appreciate your assistance on these matters,

Thank you,


I'm experiencing @itayrom's 2nd issue too. This is affecting my map control (the one Jen Underwood used in the Gartner BI bake offi) Once you start dragging the map, you can't stop. This is underlying LeafletJS functionality and not something I can control.


Resolver II
Resolver II

Hello again.

Due to the fact that all my visuals have suddenly stopped functioning, I can only assume the sandbox feature was enabled in the last few hours.

I therefore urgently request that you provide us with instructions for enabling the temporary un-sandbox flag, so we could still use our reports, until we manage to sort things out.




This is impacting me as well, and possibly one other.  Refer to this post:


Is there any guidance on how to test / debug these problems?   Why would the visual render in in the web site, but not on the iOS app?



Regular Visitor

I have 2 custom visuals that both display the same problem in sandboxing mode. One uses Leaflet and the other Cesium to display content on a geographical map or a 3D Earth. The problem is that when I grab the terrain and drag it, the visual gets stucked in this "grab and drag mode". The terrain is always dragged when I move the mouse even though I have realeased the left mouse button.

Microsoft Employee
Microsoft Employee

Hi mplus,


Thank you for reporting this. We have resolved this issue and it is making its' way to production soon.


Thank you for reporting this,


Microsoft Employee on PowerBi Platform Team

Hi Bashirs,

I am pleased to see that the problem I mentioned in my first post (the 'grab and drag' problem) has been fixed.




Update Apr 20, 2016: the problem seems to be back now.

Update May 2016: now fixed, thanks.

Hi @bashirs


It seems that custom visuals that are NOT in the official gallery don't show in iPhone dashboards. Can you confirm it?

For example, if I pin Card With States By SQLBI to the dashboard it works, but if I change its GUID (from package.json), produce a new PBIVIZ package and pin the new visual (that has the same code of the original) to the dasboard, then nothing appears in the iPhone app.


I'd also like to throw in that i'm experiencing similar issues on iOS devices since sandboxing went live.


In my report I have a few "Card with State" visuals on the initially active page which fail to render, though I see blank grey rectangles rather than the Power BI logo. If I navigate to another page and come back, they do then render, and continue to respond to changes on the page.


The "Chiclet Slicer" is also failing to render initially in exactly the same manner on that page, as well as one of my own visuals. Unfortunately mine doesn't render even when I return to the page, but the chiclets and cards do. I can't discount that my faulty visual is breaking the others, but that would seem a rather counter-intuitive to now happen given what you've tried to achieve with sandboxing. Finally, I have another visual within the same report that only appears on initially hidden pages, and that is also failing to render entirely on iOS. Other visuals on those pages render without issue.


Are there any suggestions as to how to debug a custom visual that works successfully on the web but not on iOS? Preferably something that doesn't involve having to hand over a visual to MS to fix, because that's not going to be sustainable.


On this topic, did I miss an eventual announcement that sandboxing was live, or were we expected to keep watching until something broke? The developer blog was the perfect place for all of this to be communicated, but you've for some reason abandoned it and merged it with the main blog which you seem to want to keep high level and limited to product promotion and feature announcements. A little additional communication beyond a well hidden single thread on the community forum would  have helped. Only so much however...  as has been pointed out, we couldn't test and debug on mobile platforms, and that's clearly showing now.

I've just realised after a lot of investigating the wrong thing that a bug I have in my visual will be resolved by sandboxing.


In brief, the visual (based on SVG) uses textpath elements, which are cross referenced to actual path elements using the ID.


I finally spotted that my wrongly positioned text was cross referencing the identical IDs in a differently sized instance of my visual sat on the active dashboard, which though not visible, is clearly already loaded up in the background.


As I said, sandboxing will resolve this, but I don't want to wait for this to be turned on as I think this should be easily resolvable right now by prefixing/suffixing each ID with a unique identifier tied to the overall visual.


Is there any best practice way to generate a unique ID for the current visual for use in this manner? I've considered generating a random string within init(), checking the DOM for a clashes, regenerating until unique, then using that as a prefix/suffix. I see no reason this won't work, but it feels like an inelegant workaround to a problem that might have a better solution?

Kudo Commander
Kudo Commander

I want to report a few more bugs in the sandbox mode:

  • options.viewMode in the Update method return always undefined
  • in the Init method return 0 also when a new report is created (it should returns 1). It works when onViewModeChange() happens.
  • It seems it's not more possible to call a file dialog... can you confirm it?


@danieleperilli : thank you for the report. I am not sure if all of these functions will work the same way when we finalize the visuals API. We will make it more clear in the near future and deliver something that will be guarenteed to not change in the future. We want to get to a point where we give you a set of visual APIs that are reliable and can be depended upon forever, until then there may be some reaction work to keep things up-to-date.


In the short term if you need to get around sandboxing after release there will temporarily be a feature flag to disable it as we work out enabling all of the supported scenarios for the majority of content partners.




Microsoft Employee on PowerBi Platform Team

@bashirs : You mentioned that there would be a temporary flag to disable sandboxing.  Is this available?  My custom visuals are not working and I don't know how to fix them.  I need help ASAP.

Microsoft Employee
Microsoft Employee

Hi Cmn,


There is a feature flag to disable sandboxing of custom visuals. It is triggered by adding a query string to the end of your URL. Ex:


We are of course always hard at work to improve the experience for developers while also offering the highest level of security for end users. We are hard at work to resolve any reported issues and appreciate your assistance and patience.




Microsoft Employee on PowerBi Platform Team
Not applicable

@bashirs How to achieve it from code or in pbiviz 3+ versions. Would it work once I create a package and import in PowerBI Desktop?


Please see this GitHub thread for what I want to achieve.



@bashirs, 2 problems with this approach - I can't expect all of our users to add that to the URL everytime, and more importantly, the main problem I have is with mobile apps - our custom visuals are not rendering at all on mobile.  This feature flag will not work with mobile.


Is it possible to get some concrete feedback?  Am I right in assuming that this sandbox change was deployed within the last 24 hours?  For situations like mine, how do I go about trying to find out what the problem is, and how to resolve it?


These are production reports that have been rolled out to various regional MD's within the last couple of weeks, and they are no longer working.

Microsoft Employee
Microsoft Employee

Hi cmn,


The sandbox feature has been rolling out to the various clusters over the last few days. If you are having any troubles with sandbox you can send us any error information and we can either share any work arounds or author fixes.


There are a few steps that can be taken for debugging and testing. A lot of it depends on the nature of what is "not working". If the visual is not rendering anything at all that would be different than a visual which is rendering but not reacting properly to a mouse event for example. The first thing I always look for are errors in the browser console log. If there are any error messages there or stack traces that can help identify any issues.


Can you please elaborate in more detail what is not working?




Microsoft Employee on PowerBi Platform Team

Hi Bashir,


Thanks for helping.  Here is my situation...


We have customised the Linear Gauge visualisation from the power bi visuals gallery.  We had to customise it because it is buggy and has major formatting issues.  This was working perfectly until yesterday, on both the web site, iOS app and Android app.  As of yesterday, we are experiencing the following:


1) When displayed on a dashboard on the web site, we are seeing very slow redering times - anywhere from 5 seconds to 30 seconds.  While annoying we can live with that in the short term.


2) Similar story when we drill down into a report.


3) When a dashboard is viewed in either the iOS or Android app, the gauge is never displayed.  It just shows the grey power bi logo.


4) When I drill down into a report on iOS (not sure about android), it does not display there either - it is simply a blank tile.


As well as this customised linear gauge, we also also using the CardsWithState viz (out of the box, not customised), and this behaves differently.  It works fine in all scenarios except for #4 above.  When a report is viewed on iOS, it does not render either.


As these issues are all mobile device related, I can't check for errors in the browser console log.


If you need any more details, let me know.


Thanks again for the help.

Hi Bashir,


I also depended on the hostServices.getViewMode method. Can you give an update on API availability in sandbox mode or the un-sandbox feature flag?

Helpful resources

July 2024 Power BI Update

Power BI Monthly Update - July 2024

Check out the July 2024 Power BI update to learn about new features.