Debugging tips for SharePoint developers – Solving “Unknown error occurred” and related problems

I spend some time helping the community by answering questions and suggesting solutions. Quite often people get the familiar SharePoint "unknown error occurred" message and get stuck for lack of further debugging information. Other times the log files or event logs provided by SharePoint are insufficient to help out.

SharePoint "Unknown Error Occurred"

The "Unknown Error Occurred" error is returned for a wide range of problems. It is just a generic error and without some more debugging information, finding the exact cause may be difficult.

Your first order of business is to check the log files. These are located in [12]\LOGS. Your best bet is to check the log file immediately after the unknown error occurred, the log file can fill up quite rapidly. If you are unable to check immediately, search the file for "Exception"; if the exception has been logged you will find it.

However, fairly often you might not see anything in the log files. That can be because your log sensitivity is not set high enough. You get very much control over this sensitivity level in SharePoint, but the default setting might not be sufficient in a development scenario.

Modifying logging level

To modify the logging level in SharePoint you need to go to Central administration->Operations and Diagnostic logging. your most important setting here, at least in this scenario, is the Event Throttling setting. What you are setting here is at what level errors are placed in the Windows Event Log and into the log files of SharePoint.

Note: The log files are referred to as the trace log.

You first decide which category of events you wish to modify. If you select All from the Category drop-down your changes will affect all categories. This is useful to shut up anything but what you want to see. For instance if you are having problems with workflow debugging in SharePoint you can set All categories to None in both event log and trace log files, hit Ok, and then go back to the diagnostic logging page to set Workflow Infrastructure to Verbose. By doing this your trace log files will only have Workflow related messages and should be a lot easier to investigate.

If you are uncertain to which category your error belongs, start with

The second thing you want to configure is the trace log. For development purposes you will likely have very different requirements than in a production system. While developing you expect rapid response and do not need to have hours or days of debugging information, while in a production environment that might be the exact opposite.

My recommended settings, which I actually stole from Andrew Connell in his ‘Be a better SharePoint developer through tools’ talk on TechEd US 2008, is to set a maximum of 5 logs, each holding a maximum of 5 minutes of log data.

Now that you have set more relevant logging settings, try provoking your error again and checking the trace log files. If you still do not see anything, fiddle with the different categories.

Improving the "Unexpected Error Occurred" experience

I have never understood this error. Why is an error more or less unexpected? I mean, if you are debugging, it is a good thing to be able to verify that changing a working piece of code will throw an error or exception, but how would SharePoint know which errors are unexpected?

You do have some options for getting more information when an unknown, or known error occurs. By enabling some debugging options in the web.config file of the web application you can get a full stack trace returned right on the error page when an error happens.

While this is fine in a development environment, setting these values in a production environment is not recommended.

With that caution in mind, here’s how you would enable debugging information in the web.config file of your SharePoint site:

  1. Open the web.config file, usually located in c:\InetPub\wwwroot\wss\VirtualDirectories\[portnumber]
  2. Find the element named customErrors and change the mode attribute to "Off"
  3. Find the SharePoint->SafeMode element and change the CallStack attribute to "true"

Now, rather than the meaningless "Unknown Error Occurred", the "Unexpected Error Occurred", or any other cryptic error message you get the full stack trace when something happens.

You can even set this to be the default setting for new SharePoint web applications by modifying the web.config in [12]\CONFIG directory. Be aware that modifying any file that ships with SharePoint, such as the default web.config file, is highly unsupported. Your development environment will be unsupported if you modify this file.

And now we can all laugh a bit and imagine that we care. Just never do this in your production environment, that environment should be supportable. I have yet to find any developer who has been worried abut supportability on their development environment, however.

SharePoint Log Viewer Feature

Another tip I ‘stole’ from AC is to install Scot Hillier’s Log Viewer Feature. Part of the magnificent SharePoint Features package at, SharePoint Log Viewer Feature is a simple add-on solution to your Central Administration Operations page. Upon installation and deployment of the LogViewer.wsp solution you get a new link on the operations page that leads to a useful log viewer.

To install the solution follow these steps:

  1. Download the logviewer.wsp from the link above
  2. From the command line in Windows, type
    [path to stsadm]\stsadm.exe -o addsolution -filename [path to logviewer.wsp]
    (replace brackets with your info)
  3. Deploy the solution through Central Administration->Operations->Solution Management
    still in the command line, type
    [path to stsadm]\stsadm.exe -o deploysolution -name logviewer.wsp -local

Now you should find a new link on the Operations page of Central administration leading to a new ULS log viewer page.


Just select what you want to see from the available logs and you get a much better presentation of the log information than from searching through the raw log data in notepad.

Even though this tool is extremely helpful in some cases, there are some drawbacks. You need to know to some degree what you are looking for. Unless you know to which category or severity your error belongs you will spend more time searching through information with the log viewer than without. To be honest, LogViewer is much more useful if you have some experience with debugging in SharePoint than if you are just starting out.

I hope this helps you to have a better SharePoint development debugging experience. As always, drop me a line if you have questions.


Found this article valuable? Want to show your appreciation? Here are some options:

a) Click on the banners anywhere on the site to visit my blog's sponsors. They are all hand-picked and are selected based on providing great products and services to the SharePoint community.

b) Donate Bitcoins! I love Bitcoins, and you can donate if you'd like by clicking the button below.

c) Spread the word! Below, you should find links to sharing this article on your favorite social media sites. I'm an attention junkie, so sharing is caring in my book!

Pin It

Published by

Bjørn Furuknap

I previously did SharePoint. These days, I try new things to see where I can find the passion. If you have great ideas, cool projects, or is in general an awesome person, get in touch and we might find out together.

One thought on “Debugging tips for SharePoint developers – Solving “Unknown error occurred” and related problems”

Leave a Reply

Your email address will not be published.