Monday, September 19, 2011

SharePoint 2007’s Most Common and Confusing Error

That Seems Misleading

Today I ran into an error that I was positive I’d dealt with before. When we tried to visit any System pages (those that use the default.master) in a SharePoint 2007 application, we got the following error.

The DataSourceID of 'TopNavigationMenu' must be the ID of a control of type IHierarchicalDataSource. A control with ID 'topSiteMap' could not be found.

More formally, it looked like this:

Common SharePoint 2007 Error

When we tried to load other pages (where we were loading custom user controls from disk) we got another misleading error.

An error occurred during the parsing of a resource required to service this request. Please review the following specific parse error details and modify your source file appropriately.

Another symptom and misleading error message.

Believe it or not, this is one of SharePoint 2007’s most well known red herrings. I post this in part because:

  1. A lot of the existing content on the web doesn’t fully document this error and how to troubleshoot it (misleading).
  2. I’ve run into it enough times (and forgotten the solution) that I feel a need to document it somewhere that I can easily look it up.

The Solution

The first thing to know about this error is that it gets thrown for a wide variety of reasons. While most often it has something to do with the web.config of a SharePoint 2007 web application, the root cause can get pretty tangential to a simple web.config parser error.

The first step to troubleshooting this, is to get an error message that actually speaks to the error at hand (the two above don’t, so don’t try to troubleshoot off of them). This genre of error seldom puts helpful details into the event log and so you should:

  1. Open up the latest log file in the 12 hive (C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Logs).
  2. I usually go to the end of the file and search up for terms like “error” or “exception”.
  3. You should be able to find some error. These can be quite varied from type/assembly resolution errors to parsing in the web.config.
  4. From here troubleshoots typically go one of two routes.
    • Either the error itself will inform you of what to do (e.g. a file is missing somewhere).
    • You still have no idea and need to manually merge back in a working web.config.
  5. If you can’t figure out what to do based on the error, 99% of the time you can repair the error by merging in (use a diff tool, don’t blindly stomp) a stock SharePoint web.config. To do this…
  6. Backup your failing web.config.
  7. Create a blank web application in some test farm.
  8. Diff in (we use Beyond Compare) the newly provisioned stock web.config into your failing one (preferably line by line to determine root cause).
  9. After you bring a line/section over feel free to save the file and refresh your browser. Every time you change the web.config (and save) the application pool should recycle, so don’t worry about needing to reset IIS.

This “baby steps” process has always yielded a quick troubleshoot down to root cause for us.

Troubleshooting SharePoint errors is often the beginning of a frustrating afternoon, so hopefully this helps someone out there.

My Best,

No comments: