"An unexpected error has occurred." You've seen it before, usually right around the time you're trying to do some important work. SharePoint's non-informative error message leaves you wondering what just happened — did I type something wrong? Did the server just crash? Did I just break SharePoint? In this post, I'll provide an overview of SharePoint's diagnostic logs and how to easily find the error information (skip to Getting the Error) so you can begin to figure out how to resolve your SharePoint problems.

SharePoint Error: An unexpected error has occurred

The SharePoint "Error" message replaces a technical error that historically IIS displayed. You can still get IIS to display the error and dump out the call stack to the user's browser with some changes to the web application's web.config file. This is typical for a development or test environment, however since this reveals sensitive information to the user who could in turn use this information maliciously, it's a security best practice to leave this information hidden behind the SharePoint error message for production systems.

Behind the scenes of everyday use, SharePoint saves the details of errors and other diagnostic information to a log file on the server where the error happened. In multi-server farms you'll need to figure out which server has the record of the error, and if it's not immediately obvious where the error happened you'll need to check every server in the farm. These log files are known by a few names: the Unified Logging System (ULS) logs (their official name), Trace Logs (from the SharePoint UI and MSDN documentation), or the diagnostic logs which is a commonly used name throughout the community. These logs are text files where each line contains a unique event (though some events like exceptions may span multiple lines because of the large amount of text in the error message). In each line will be a time stamp, the related farm component, a severity, a description of the problem, and other information relevant to the event. You can open these files with Notepad or your text editor of choice. You can also use a SharePoint log viewing tool. Microsoft has one such tool called ULSViewer that I will demonstrate later in this post.

The ULS logs can be configured with Central Administration or PowerShell. By default they are stored in the SharePoint hive in the LOGS folder and contain a suitable amount information from SharePoint components to aid in most troubleshooting efforts. In general, most exceptions will appear here so it's safe to assume that when a user sees the Unexpected Error message there will be a record of it in the logs. The log files themselves are named with the format "SERVERNAME-YYYYMMDD-HHMM.txt" where SERVERNAME is the server's computer name, YYYYMMDD is the current date, and HHMM is the time the log was started using a 24-hour clock.

Trace log settings in Central Administration

SharePoint 2010 improved the logging capabilities from the previous version by adding a Correlation ID to all errors. You can see it in the first picture in this post (d36b5f25-7839-4581-ac9b-5a6e498796cc). It used to be that SharePoint administrators would have to comb through the logs to find any errors around the time the user experienced the problem.

The Correlation ID doesn't just map an instance of the error to the error's details; it actually is added to every log entry for a particular set of events. When you browse to a page in SharePoint, it will create a set of log events for every action SharePoint takes to serve up that page, each tagged with the Correlation ID. The best part is that these events are sandwiched between a starting event and an ending event, also with the Correlation ID, so you know where in the file you can start and stop reading. This is handy and so simple, it makes tracking down errors fun.

As I mentioned, ULSViewer is a tool from Microsoft for looking at ULS logs. You can either open existing log files or have ULSViewer display a real-time list of events as they are being logged. This is really useful when trying to trace an issue as it happens, and even though there is a potential for a lot of events to be written to the log there is the option to filter out everything except what you're looking for. When opening an existing file filtering by Correlation ID is often the easiest way to find what you need.

Getting the Error

At the top of this post, you'll find a typical SharePoint Error message with a Correlation ID. The first step is to note this Correlation ID; copying it from the browser is the easiest method. About 9 times out of 10 when you select the Correlation ID it will also copy a space at the end — just note that when you later paste the text you'll need to remove this space.

Next, you'll want to open the ULS log that contains the error. In single server farms open the log from the day and time which the error happened. In multi-server farms you'll need to go to the specific server where the error happened to locate the log. Start with the WFE server that handled your request. This can be hard to determine in a farm with multiple WFE servers and a load balancer. If the error isn't in the WFEs, check the application servers. Unless you've installed SharePoint on your database servers it is unlikely there are ULS logs there so you won't need to check them.

Start ULSViewer and open an existing ULS log (File -> Open From -> File, or press CTRL+O):

Opening a ULS log

If you're not sure where the ULS logs are stored, check Central Administration or you can use ULSViewer to tell you by opening the real-time log (File -> Open From -> ULS, or press CTRL+U). Note the folder and go back to opening an existing log.

Use the ULS Realtime mode to discover the location of the ULS logs

When the file opens, edit the filter by either clicking the filter icon on the tool bar, from the edit menu (Edit -> Modify Filter), or by pressing CTRL+M. The Filter by... window will open. To filter by the Correlation ID, create the filter:

  • Field: Correlation
  • Operation: Equals
  • Value: d36b5f25-7839-4581-ac9b-5a6e498796cc (You would enter the Correlation ID you copied from the SharePoint Error message, remember to remove the trailing space if it's present!
  • And/Or: And
Editing a filter. Field: Correlation, Operation: Equals, Value: your Correlation ID, And/Or: And

Click OK and ULSViewer will show only the events that have this Correlation ID:

A filtered list of events with the Correlation ID

If there are no events this means this log file doesn't contain the error. Try another log file around from around the same time and date. In multi-server farms you'll need to check other servers if you can't find the error.

Now you can click through the events until you find the exception. You can usually spot these from the list as they will contain a value in the Level column of Unexpected. In the screenshot above you can see that there are three Unexpected events (in the screenshot above, the events are in rows 4, 12, and 14). Check each of them, though the first one is likely the most relevant. You could further refine your filter to only return the unexpected events. I don't recommend this as I find it's best to see the exception in context as this can provide a clue to the root cause.

Let's look at our exception. When you click on an event, ULSViewer will show the exception message in an area near the top:

Selecting the exception

Now we can finally see the real error! If you double click the event, the ULS Entry Viewer window will open to show all of the details much like the Windows Event Viewer.

Exception event details

You can now begin your troubleshooting investigation! Use this error in searches and of course in any forum posts as this message is critically useful information to help diagnose the issue. Be sure to remove or anonymize any identifiable information like server names before posting if you don't want this information public.

Bonus Content!

Sometimes your server doesn't have Internet access or you can't install ULS Viewer on the server, or you can't get a copy of the log file to open on your local machine. Sometimes you're being lazy or just trying to find the event quickly. In all of these scenarios you can open the ULS log in Notepad and use the Find feature to locate the Correlation ID. Once found, I use the following trick to copy out all of the related events to make it easier to read:

  1. Open the ULS log file with Notepad
  2. Find (Edit -> Find, CTRL+F, or F3) the Correlation ID. Remember to delete the trailing space if it's present.
  3. When found, move the cursor to the start of the line (press Home to go to the start of the line). Press Enter. This will put a line break before the event.
  4. Repeat the find until Notepad can no longer find the Correlation ID.
  5. Go to the end of the current event (press End to go to the end of the line). Press Enter. This will put a line break after the event.
  6. Copy all of the text between the two line breaks into a new text file (or whatever application you wish) to inspect. Remove any unrelated lines if necessary. Don't save the original log file, you do not want the line breaks.