Troubleshooting SharePoint Solutions
The following problems or alerts might occur when you debug SharePoint solutions by using the Visual Studio debugger. For more information, see Debugging SharePoint Workflow Solutions.
This topic contains the following sections.
- Character Restrictions in Project and Project Item Names
- Errors When Creating Custom Fields
- New Non-English Site Definitions Do Not Appear in Site Creation Page After Deployment
- Error Appears When a Workflow Project Is Deployed on a Clean System
- User Must Refresh Application Page in Browser While Debugging to View Updated Image
- Error: The Site Location Is Not Valid
- Site Deletion Web Event Does Not Occur in Event Receiver Project
- Deployment Error Appears After the Name of an Identifier in a Business Data Connectivity Model Project Is Changed
- An Error Appears When You Try to View a Visual Web Part in SharePoint
- Error Appears When an Imported Reusable Workflow That Contains a Task Form Field Is Run
- Error Appears When a Renamed Imported List Instance Is Run
- SharePoint Debugging Session Terminated By IIS
- Auto-Retract Leaves Orphaned List Instance in SharePoint
- Original SharePoint Solution is Replaced by an Exported Version
- Error Appears when Starting Debugging
- Related Topics
Character Restrictions in Project and Project Item Names
Project and project item names can contain only characters that are valid in a deployment path in SharePoint 2010. No other characters are allowed.
Error Message
“Invalid characters” error message.
Resolution
For SharePoint project and project items names, use only the following characters:
Alphanumeric ASCII characters
Space
Period (.)
Comma (,)
Underscore (_)
Dash (-)
Backslash (\)
When a project is packaged, a validation rule verifies that the Deployment Path property for each file being deployed contains only these valid characters.
Errors When Creating Custom Fields
Custom fields in Visual Studio 2010 are defined in XML. If a field is not defined or referenced by using a specific format, errors can occur.
Error Message
“Invalid characters” error message at packaging time.
Resolution
The ID for a field definition must be a GUID surrounded by braces. For example,
<Field ID="{5744d18c-305e-4632-8bd1-09d134f4830d}"
Type="Note"
Name="PatientName"
DisplayName="Patient Name"
Group="A Custom Group">
</Field>.
A field reference in a content type must be defined by using the empty element format (<FieldRef />), not by using start/end elements (<FieldRef></FieldRef>). For example:
<FieldRef ID="{5744d18c-305e-4632-8bd1-09d134f4830d}"
Name="PatientName"
DisplayName="Patient Name"
Required="TRUE"/>
If there is a problem with the source XML for the field, such as it is malformed or not a valid XML file, then the error "Cannot parse file" occurs.
New Non-English Site Definitions Do Not Appear in Site Creation Page After Deployment
After creating and deploying a new site definition using a non-English version of Visual Studio 2010 (that is, a version with a locale ID other than 1033), the SharePoint Customizations tab does not appear in the Template Selection box and the new site template does not appear in the New SharePoint Site page.
Error Message
None.
Resolution
This problem occurs because of an incorrect value in the Path property for the webtemp site definition configuration file, such as webtemp_SiteDefinitionProject1.xml. In the Path property for the webtemp file, located under the Deployment Location, change 1033 to the appropriate locale ID. For example, to use a Japanese locale change the value to 1041. For more information, see Locale IDs Assigned by Microsoft on the MSDN Web site.
Error Appears When a Workflow Project Is Deployed on a Clean System
This problem occurs if you deploy a workflow project in Visual Studio 2010 on a clean system. A clean system is computer that has fresh installation of Visual Studio 2010 and SharePoint, but no deployed workflow projects.
Error Message
Cannot find the SharePoint list: Workflow History.
Resolution
This error occurs because of a missing Workflow History list. Because the development environment is a clean system, no workflows are deployed and the Workflow History list does not exist yet. To resolve this issue, reopen the workflow wizard, which causes the Workflow History list to be created.
To reenter the workflow wizard
Select the workflow node in Solution Explorer.
In the Properties window, click the ellipsis (…) button on any property that has an ellipsis button.
User Must Refresh Application Page in Browser While Debugging to View Updated Image
If you are debugging a SharePoint solution that contains an application page with a control that displays an image, such as an HTML Image control, you must refresh the page in the browser to display any changes that were made to the image.
Error: The Site Location Is Not Valid
This problem can occur if SharePoint Server 2010 is not installed. It might also occur if you do not have administrator access to the SharePoint Web site that is specified in the SharePoint Customization Wizard.
Error Message
- SharePoint site location is not valid.
Resolution
Install SharePoint Server 2010.
Ensure that you have administrator access to the SharePoint Web site. For more information, see the Office Online article Grant access to the portal site.
Site Deletion Web Event Does Not Occur in Event Receiver Project
When you create an event receiver project and you select certain Web events such as "a site is being deleted," the event never occurs.
Error Message
None.
Resolution
This problem occurs because the feature scope must be "Site" to handle site-level events, but the default feature scope for event receiver projects is "Web". The Web events affected are:
A site is being deleted (WebDeleting)
A site was deleted (WebDeleted)
A site is being moved (WebMoving)
A site was moved (WebMoved)
To fix the problem, change the feature scope of the event receiver, as follows.
To change the feature scope of the event receiver
Open the event receiver's feature in the Feature Designer. To do this, double-click its .feature file in Solution Explorer.
Click the drop-down arrow next to Scope.
Select Site in the drop-down list.
Deployment Error Appears After the Name of an Identifier in a Business Data Connectivity Model Project Is Changed
This problem occurs if you change the identifier name of an entity in a Business Data Connectivity (BDC) model and then try to deploy the solution.
Error Messages
<model name> has the following External Content Type activation errors ...
The IMetadataObject with Name '<model name>' has a value in Field 'name' that is duplicated ...
Resolution
To resolve this issue, delete the model manually, and then deploy the solution again. You can delete the model by using either of the following tools:
SharePoint 2010 Central Administration. For more information, see BDC Model Management on the Microsoft TechNet Web site.
Windows PowerShell. You can delete the model by typing this command at the command prompt: Remove-SPBusinessDataCatalogModel. For more information, see General cmdlets (SharePoint Server 2010) on the Microsoft TechNet Web site.
An Error Appears When You Try to View a Visual Web Part in SharePoint
This problem occurs when the Path property of the user control does not begin with the string "CONTROLTEMPLATES\".
Error Messages
The file '/_CONTROLTEMPLATES/<project name>/<Web Part name>/<user control name>.ascx' does not exist.
Server Error in '/' Application.
Resolution
To resolve this issue
In Solution Explorer, select the user control file. This file has the .ascx file name extension.
On the View menu, click Properties Window.
In the Properties window, expand the Deployment Location node.
Ensure that the value of the Path property begins with the string "CONTROLTEMPLATES\"
Error Appears When an Imported Reusable Workflow That Contains a Task Form Field Is Run
This problem occurs if you import a workflow that contains a task form that has a field, and then run the new workflow on the same system from which you imported it.
Error Message
Error occurred in deployment step 'Activate Features': The field with Id [Guid] defined in feature [Guid] was found in the current site collection or in a subsite.
Resolution
This error is the result of field ID collisions that occur because the Import Reusable Workflow project in Visual Studio does not change task form field IDs. If you deploy an imported workflow on the same server that contains the original workflow, field ID collisions occur.
To resolve this issue, use the Find and Replace feature to change the value of the Field ID attribute in all of the imported workflow files.
Error Appears When a Renamed Imported List Instance Is Run
This problem occurs if you rename an imported list instance and then run it in Visual Studio.
Error Message
Build error: Error occurred in deployment step 'Activate Features': The file Template\Features\[import project feature name]\Files\Lists\[old list name]\Schema.xml does not exist.
Resolution
When you import a list instance, an attribute named CustomSchema is added to the Elements.xml file of the list instance. Elements.xml includes the path of a custom schema.xml for the list instance. When you rename the list instance in Visual Studio, the deployment path for the custom schema.xml changes, but the path value of the CustomSchema attribute is not updated. As a result, the list instance cannot find the schema.xml file in the old path that is specified by the CustomSchema attribute when the feature is activated.
To resolve this issue, update the path of the deployment location of the schema.xml file in the CustomSchema attribute.
SharePoint Debugging Session Terminated By IIS
This problem occurs if you set a breakpoint in a Visual Studio SharePoint solution, press F5 to run it, and then remain at a breakpoint longer than 90 seconds.
Error Message
The Web server process that was being debugged has been terminated by Internet Information Services (IIS). This can be avoided by configuring Application Pool ping settings in IIS. See help for further details.
Resolution
By default, the IIS application pool waits 90 seconds for an application to respond before it closes the application. This process is known as "pinging" the application. To resolve this issue, you can either increase the wait time or disable application pinging entirely.
To access the IIS app pool settings
Open IIS Manager.
In the Connections pane, expand the SharePoint server node and click Application Pools.
On the Application Pools page, select the SharePoint application pool (typically "SharePoint - 80") and then, in the Actions pane, click Advanced Settings.
To increase the wait time before IIS timeout, change the value of Ping Maximum Response Time (seconds) to a value larger than 90 seconds.
To disable IIS pinging, set Ping Enabled to False.
Auto-Retract Leaves Orphaned List Instance in SharePoint
This problem occurs if you take the following steps.
Create a list definition that has a list instance in Visual Studio 2010.
Run the solution by pressing F5.
Stop debugging, or close the SharePoint site.
Reopen the SharePoint site and open the list instance.
Error Message
Server Error in '/' Application.
Resolution
This happens because after you close a debug session of a SharePoint solution, the auto-retract feature retracts the solution. The retraction deletes the list definition from SharePoint but does not delete the instance of the list. The underlying list definition is required by the list instance.
To resolve this issue, on the Build menu, click Deploy to deploy the solution. (Do not use F5 to debug it.) Then, delete the list instance in SharePoint.
Original SharePoint Solution is Replaced by an Exported Version
If you export a SharePoint solution, import the solution into Visual Studio, and then deploy the solution back to the same site from which it was exported, the original SharePoint solution is replaced. This problem does not occur if you deploy the solution to a server that does not have the original solution activated on it.
Error Message
None.
Resolution
To avoid overwriting a solution on the site from which it was exported, change the GUIDs of the SolutionID and the Feature IDs of all the imported features in the Visual Studio project.
Error Appears when Starting Debugging
When you start debugging a SharePoint solution in Visual Studio, you get an error that Visual Studio could not load the Web.config configuration file because the given key was not present in the dictionary.
Error Message
Could not load the Web.config configuration file. Check the file for any malformed XML elements and try again. The following error occurred: The given key was not present in the dictionary.
Resolution
To resolve this problem, make sure that the Site URL property value of the SharePoint project in Visual Studio matches the URL assigned to the Default Zone for the alternate access mappings of the web application. Using another zone, such as Intranet, for the URL will not resolve the error. The project’s Site URL and the URL in the Default Zone must be the same. To access alternate access mappings, click Application Management in the SharePoint 2010 Central Administration utility, then click the Configure alternate access mappings link under Web Applications. For more information, see Create zones for Web applications.
See Also
Concepts
Troubleshooting SharePoint Packaging and Deployment