SharePoint Tip of the Month

SharePoint Debugging Tips

September 2014

SharePoint has a robust event logging system.  By default, the SharePoint log files are located in the “Logs” folder in the SharePoint “hive.”  One tool used to analyze these log files is the ULS Viewer.  This program works with both SharePoint 2010 and 2013 log files and recently been updated; it now includes the ability to monitor multiple servers in the farm, output formatting, and other new features.  Using this program, you can view earlier log files as well as monitor, in real-time, as events happen.

As an example on how to debug SharePoint issues, let’s say that a user has reported that an error has occurred while uploading a group of documents to a SharePoint document library.  Usually, when an error does occur, the system will report back a description of the error; however, in this case, a general “unexpected error” message popped up, and the user was able to take this screenshot of the error:

Error Message

Note that the message includes a “Correlation ID” and the date/time of the occurrence.  These two pieces of information are key to tracking down the exact nature of the error, for the SharePoint logs contain a lot of data.

Let’s open the appropriate SharePoint log file for analysis.

Step 1: Open the ULS Viewer application, then go to the “File” menu, then “Open From” and then select “File”.

Open File

Navigate to the SharePoint “Logs” folder (for SharePoint 2010: “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\Logs”; for SharePoint 2013: “C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\Logs”) and open the log file for date/time in question.

Search Log Files

Note the formatting of the names of the log files; they are date and time stamped in a specific format.  In this case, the error occurred at 9:45 am on August 25, so the information for that error would be in the “DEV-20140825-0940.log” file, with “20140825” corresponding to August 25 and “0940” corresponding to 9:40 am (the time that SharePoint began logging entries to this particular log file).

Step 2:  Once the log file has been opened, you will see that there are many entries. Let’s filter the entries based on the correlation ID in the error message.  In the “Edit” menu, click on “Modify Filter.”  In the first row, in the dropdown for “Field,” select “Correlation;” in the dropdown for “Operation,” select “Contains” (this may already be selected); in the “Value” column, enter in the correlation ID from the error message (in this case, it is “0c3379e2-5038-4095-93c3-6c58ce18dbb8”).  Then click “OK.”

Filter By

This effectively filters the log files to only show log entries corresponding to the particular error.

Step 3: From here, an administrator/developer can select each entry to pinpoint exactly where the error occurred and can come up with a solution.

Filtered Results

In the screenshot of the filtered results, you can see that the ULS Viewer has highlighted a critical error, which also assists with debugging.  Note that formatting and highlighting within the ULS Viewer is customizable.

Debugging with PowerShell

There are also two PowerShell commandlets that can be used to retrieve log entries.  One is the “Get-SPLogEvent” commandlet, which is better suited for smaller SharePoint installations (1-2 servers).  The other is the “Merge-SPLogFile”, suited for larger SharePoint enviroments (3+ servers) where the exact server on which the error is occurring is not known.  These commandlets are run within the SharePoint Management Shell.

The following PowerShell command could be used to view the log entries for the sample error:

Get-SPLogEvent –StartTime “8/25/2014 9:40 am” –EndTime “8/25/2014 9:50 am” | ? { $_.Correlation –Match “0c3379e2-5038-4095-93c3-6c58ce18dbb8” } | fl

Note the “-StartTime” and “-EndTime” parameters. Since the date/time of the error is known, these can be used to force the commandlet to only search log entries during this time frame, providing faster results.  Also note that the commandlet is filtering based on the correlation ID.

The “Merge-SPLogFile” PowerShell commandlet works in the same way; however, it will search all of the log files in all of the SharePoint servers and place the search results in another log file.  The previous “Get-SPLogEvent” command can be converted to “Merge-SPLogFile” like so:

Merge-SPLogFile –path “c:\newlogfile.log” –StartTime “8/25/2014 9:40 am” –EndTime “8/25/2014 9:50 am” –Correlation “0c3379e2-5038-4095-93c3-6c58ce18dbb8”

Note that this commandlet also has “-StartTime” and “-EndTime” parameters as well as a specific “-Correlation” parameter.  The resulting log file can then be opened and analyzed in a log viewer, such as the ULS Viewer mentioned previously.

Other Debugging Tips

Here are some other general quick checks of the SharePoint environment that should be performed, if possible:

  • Are all of the SharePoint websites up and running in IIS?  Restarting the affected website could help.
  • Are all of the SharePoint application pools running in IIS?  Restarting the affected application pool could help.
  • Are all of the SharePoint system services (OWSTimer, OSearch, etc.) running as necessary on each SharePoint server?
  • Are all of the SharePoint servers up and available?  Can they be “ping”ed?
  • Have any of the SharePoint servers run out of disk space?

In conclusion, debugging SharePoint errors can appear to be a daunting task; however, having a few bits of key information, such as the error date/time and the correlation ID, and using the right tools can help to lead to rapid and successful SharePoint issue resolution.

This TOTM was contributed by SharePoint Consultant, Tommy Byrd.