When developing SharePoint Add-ins, it is often the case that newly created/developed projects won’t deploy to a site straight away. There can be many reasons for this and getting to the bottom of why the Add-in instance deployment fails isn’t helped by a vague ‘something went wrong’ message on the Site Contents page.
Many SharePoint developers will have come across this tile on the Site Contents at some point…
Hardly an inspiring or meaningful message from which to start debugging any issues, is it?
Before we get carried away trying to get into in-depth debugging activities though, sometimes clicking the ‘Click to retry’ option can make it work the second (or third) time. If the farm is busy then I’ve seen app install jobs timeout in the web browser before they get executed and getting it to work can simply be a case of running it again a couple more times.
If re-running the job doesn’t work then there are a few other things you can try, and the first one I always go for is to try installing a different Add-in on the same site to check if installation of all apps is failing or only the one I’m developing. If it is all apps, then consider following the steps in this article to fix any wider app installation issues.
Assuming we’ve identified our in-development Add-in as the only one failing then the first thing to do is check the app details. Hover the mouse pointer over the ellipsis (…) for the app’s tile on the Site Contents page. Choose the ‘DETAILS’ option on the pop-up pane that is displayed.
You should see something similar to the screen-shot below displayed on as a web page, and it is the Install Errors entry you want to look at. Click on the number and the installation errors should be listed, similar to that shown here:
Unfortunately, from this point forward we need to start digging into SharePoint’s ULS logs for some answers. Notice the right-most column called “Correlation ID”. It is this value that we’ll need to use to filter the ULS logs and get to our debugging data.
Microsoft provide a ULS log viewer tool called ULSViewer which is available here (at the time of writing). You can open ULS log files and view them using this tool and filter entries based on correlation ID.
If your farm consists of multiple servers (and most do), then you may want to consider merging the log files before continuing to the next step, and this article explains how. If you are on a single server environment or know which server in the farm the ULS log files relating to the issue are going to be on you can simply log into that server and access them directly.
Either way, open the ULS log file (merged or otherwise) in ULSViewer and then filter on the correlation ID. (If you get no results, you are probably looking at the wrong ULS log file or have chosen a log covering the wrong timeframe.)
Once we’ve got a set of log entries we can start interrogating them. In most cases this will be a site issue (e.g. pathing), corruption of assets distributed by the add-in (e.g. list specs), etc. The ULS log entries should be sufficient to identify the root cause of the issue and fix it.
This article won’t go into details of lots of specific issues, as there can be many different ones, but the most likely cause of failure is feature installation/activation. Look for messages that start with something like “Feature Activation: Threw an exception, attempting to roll back”. The message(s) describing the error will usually immediately precede them (i.e. previous few messages).