I’m currently working with a team of very talented ASP.NET developers who are diving into SharePoint development for the first time. They’ve raised some very common questions regarding errors they’ve come across as they’ve started development, and I thought I’d go ahead and post some of their questions, and the accompanying answers, in case it helps some other folks out there as well.

Q: I have a functioning web page, then after I deploy my solution package, I get a 404 error message. If I retract my solution, the page is still there. What happened?
A: A 404 error indicates the page is truly gone. However, you’ve pointed out that the page isn’t really gone; it’s still there. That would leave you to believe that it’s some other resource that’s missing. Well, what other resource is used by a page in SharePoint? That’s right, a master page! If you get a 404 error on every page in your site, it probably means the master page property for your site has been set to a URL of a master page that doesn’t exist. To fix this problem, type in the URL for the Site Settings page (which should always work, even if your master page is broken.) The Site Settings page’s URL is the URL of your site, followed by /_layouts/settings.aspx. From the Site Settings page, click on the “Master page” link under the Look and Feel section to reset your master page to an out of the box one. This will at least get your site usable in the meantime.

If you notice you get a 404 error on only one page in your site, and that page is a publishing page, it could be that its associated page layout was not deployed properly

Q: We’re using source control to manage our Visual Studio 2010 project. Someone added a file to the project and now when I try to deploy my solution, on the Feature Activation step, it says it can’t activate a feature. What happened?
Visual Studio keeps track of which files are in which node (i.e. which files are part of a Module node, an Element node,  a mapped folder, etc.). If you click on the “Show all files” button at the top of your Solution Explorer in Visual Studio, you’ll see that each node or folder has a file called SharePointProejctItem.spdata. Every time you move a file from one location to the other, or you delete or add a file, Visual Studio automatically makes changes to the .spdata file to reflect the change. If you are using Source Control, it could be that that file is checked in, it’s locked, so Visual Studio can’t make the appropriate changes to it, at which point the file is inconsistent with the files in its folder or node. In the case of the example mentioned in the question, you can run into problems if an old feature was removed and Visual Studio still thinks it’s there and is trying to activate it.

Q: I modified the web.config file in my IIS web application folder, but I still can’t seem to get errors to show up, even though I set the customErrors node to “Off”. Why can’t I see my error messges?
Believe or not, there is an additional web.config file in the LAYOUTS directory of your SharePoint root folder (at ~/14/TEMPLATE/LAYOUTS). You need to set the customErrors node to “Off” here, too.

Q: I built a page layout in SharePoint Designer and then copied the markup into Visual Studio so I could deploy it as a solution package. It deployed it the first time successfully, but now, when I make changes to it and redeploy it, it doesn’t reflect my changes. Why not?
A: When you create a page layout in SharePoint Designer, the following tags automatically get added to the Page directive at the very top of the page:

meta:webpartpageexpansion="full" meta:progid="SharePoint.WebPartPage.Document

These tell SharePoint that the page is customized. When you deploy your page layout using a solution package, even if it has never been customized, and should be pointing to the markup file on the file system in your feature folder, SharePoint will see those tags and think the page layout has been customized, so it will no longer look at the file system. Make sure you always remove these tags from the top of your page before you try to deploy your page layout from a feature.

Q: I’m using LINQ to SharePoint but I’m noticing that not all my publishing columns are included in the class file that gets generated by SPMetal. I need to use those fields! What do I do?
A helpful solution I got from Andrew Connell is to create a partial class with your publishing column information. This will combine with the automatically generated class information to create a fully functioning class. Read about it here: http://www.andrewconnell.com/blog/archive/2010/07/28/extending-linq-to-sharepoint-entity-models-for-sharepoint-server-2010.aspx.

There are quite a few little gotchas when starting SharePoint development, but the great thing is, once you know a fix for your problem, you’ll never be paralyzed by that problem again. For new developers out there, hang in there!