A good part of my time I’m working on troubleshooting issues with SharePoint 2010 farms. Usually this includes (but is not limited to) unexpected errors and performance problems. In this blogpost I will describe some of the tools and tricks I use on a daily basis to pinpoint the source of problems.

 

Unexpected errors

We all know them, right? “An unexpected error has occurred”.

 

 

Now what? To get a more descriptive message about what might be wrong, there are two approaches:

 

1) Edit the web.config file

2) Check the SharePoint log files

 

Approach 1: Edit the web.config file(s)

In order to show the underlying (.NET) error message that is causing SharePoint to show you “An unexpected error has occured”, you can change some settings in the web.config file. Please note: only do this in a development environment, and NEVER in a production farm. In production environments revert to approach 2 described below. Showing the .NET error message to users looks ugly and more importantly causes a security risk.

 

On each of the web frontend servers in the farm change the following settings in the web.config file:

 

<SafeMode MaxControls="200" CallStack="false" DirectFileDependencies="10" TotalFileDependencies="50" 
        AllowPageLevelTrace="false">

 

to

 

<SafeMode MaxControls="200" CallStack="true" DirectFileDependencies="10" TotalFileDependencies="50" 
   AllowPageLevelTrace="false">

 

This makes sure you see the whole stack when the error message is shown on the screen. Also change

 

<customErrors mode="On" />

 

to

 

<customErrors mode="Off" />

 

This makes sure the .NET error is shown on screen instead of the SharePoint default custom error. Changing a web.config file recycles the application pool of the webapplication on the frontend you are editing the web.config file on. This is why the page takes a bit longer to load after editing a web.config file.

 

Note: The web.config file can typically be found in C:\inetpub\wwwroot\wss\VirtualDirectories\webapphostheader:portnumber

 

Now my error looks like this:

 

 

Note that this only works when the error occurs on a “regular” page. When developing application pages that live on the file system in the LAYOUTS folder, a second web.config file is involved. This one is located in the folder

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS. In this web.config file change

 

<customErrors mode="On" />

 

to

 

<customErrors mode="Off" />

Now the full error is shown on the application page.

 

Approach 2: Check the SharePoint log files

This is the preferred approach, even for your development machine. You should be able to quickly locate an error in the SharePoint log files.

 

The number one tool for reading SharePoint log files is ULS Viewer. The SharePoint logfiles are located in the folder that is set in the central admin under Diagnosics Settings. To view which folder this is go to Central Administration –> Monitoring –> Configure Diagnostic Logging

 

 

The Trace Log Location is under path. In my case it is set to c:\LogFiles\Diagnostic

 

This will be the location of the diagnostic logfiles on all the servers in the farm. In case of a multi server farm, your error is logged to the frontend that is handling the request. This can be very inconvenient in a farm with more than one frontend, since you usually don’t know what frontend is handling (or has handled) the request. It is not neccessary to check the diagnostic logs on all the front-ends seperately. For this my favorite PowerShell commandlet was invented: Merge-SPLogFile. If you are working with a single server farm (like your development machine), you can skip this step of course.

 

Merge-SPLogFile does exactly what the name implies: it merges the diagnostic logfile from all the servers in the farm into one file. We can then open this file in ULS Viewer to look for our error. Pretty neat. Here is how I usually use Merge-SPLogFile:

 

Merge-SPLogFile -Path c:\log_20120328.txt -StartTime "28-03-2012 12:40"

 

Giving a StartTime makes sure only log entries from that point in time on get merged. If you ommit this parameter, you might get a very big merged file (multiple GB's). There is also an EndTime parameter if you want to merge logentries for a certain timeframe. I always try to narrow the time frame as much as possible to the time that the error occured. In that case the merged logfile is not too overcrowded with entries.

 

If you enter the command (run the PowerShell window as Administrator to ensure you have sufficient rights to execute) it starts working, showing a progress bar:

 

When the operation is finished, it is time to fire up ULS viewer and look for the error. So we start ULS Viewer –> File –> Open From –> File.

 

 

Note: The option Open From –> ULS is also pretty cool. It shows you realtime data from the diagnostics logfiles, but only for the server you are currently logged on to. But in our case we want to upen up the newly merged logfile we just created. So I select c:\log_20120328.txt.

 

Then the first thing I do is turn off all the little buttons in the middle top of the screen. This filters out all the Verbose, Warning and High messages from the log. Since an Unexpected Error falls in the category Unexpected (duh!) this leaves us with only our error. Click on it to see the whole stacktrace:

 

 

In the screenshot you see the error three time because I’ve refreshed the page with the error three times.

 

Summary

There are several ways to find out what causes the dreaded “An unexpected error has occured” message. This acticle describes two of the approaches possible and describes some of the tools that you can use in SharePoint 2010 troubleshooting