Custom MasterPages and SharePoint Hosted Apps

We all know that Microsoft is moving away from the concept of Custom Masterpages (at least on Office 365). Chris O’Brien explains some considerations in this great blogpost–thoughts.html. But say you already have this On Premises SharePoint 2013 Intranet with a nice custom MasterPage in place on a Publishing Site. When you have subsites and especially Team Sites, there is this scenario, when setting the MasterPage, you want to force the MasterPage on all subsites.

Inheritance of the MasterPage

When you stick to Publishing Sites, a new subsite will always inherit the MasterPage from its RootWeb by default. However when mixing publishing sites with a Team Site for instance, things get tricky. Because the publishing Web Feature is not activated on a Team Site, no MasterPage is inherited.



I also deployed a SharePoint Hosted App to the Root Web. Just an Hello World App to illustrate this issue.


If you activate the Publishing Web feature on the Team Site, inheritance is immediately restored. Unfortunately there is another, more harmful, way to force the MasterPage. If you go to Site-settings > MasterPage on the Root Web you can check the box “Reset all subsites to inherit this site master page setting”.


By doing this you can force the MasterPage upon all the subsites in this sitecollection. Because our subsite is a Team Site we need to set the System MasterPage as well. When I select my custom MasterPage at first sight nothing happens and everything is OK. (I only changed the SharePoint brand in the top left Suitebar into a custom text).


Oops! My Apps broke down

After I reset the MasterPage to all subsites when I open up my SharePoint Hosted App, suddenly this error appears (CustomErrors are off).


This error instantly tells us what’s wrong. By resetting the MasterPage to ALL subsites, the App Webs are updated as well, therefore introducing a reference issue because the MasterPage is now linked to the Host Web’s MasterPage instead of app.master on it’s own App Web.

Powershell to the rescue

The easiest solution is to remove the App and add it again to the site but in most cases this don’t want to do this. Especially when there is data in the App Web. Using powershell to repair the MasterUrl is the obvious solution here. The code I provide here is based on an On Premises environment. When using Office 365 you will have to write some additional code to make the connection.

Famous last words

This error occurs only in this very specific scenario and if the reset is applied for the System Master Page. When you reset all sites to use the Custom Master Page all apps will keep working. In my experience this specific scenario occurs when mixing up Publishing Sites with Team Sites. Because Team Sites don’t inherit and you can’t set a Team Sites MasterPage from the Site Settings.

Leave a Reply

Your email address will not be published. Required fields are marked *