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.
- Token Restrictions in Sandboxed Visual Web Parts
- Character Restrictions in Names of Projects and Project Items
- 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 Debugging Starts
- Related Topics
Token Restrictions in Sandboxed Visual Web Parts
Visual web parts in sandboxed solutions can't process standard tokens, such as $SPUrl, that the SharePoint runtime supports. As a result, the URL isn't resolved, and you can't preview the content in Design view in the visual web part designer if you refer to it directly in a script element, such as in the following example:
<script src=”<% $SPUrl:~site/SiteAssets/ListOperations.js %>"></script>
To work around this limitation and resolve the token, refer to it by using literals:
<asp:literal ID="Literal1" runat="server" Text="<script src='" />
<asp:literal ID="Literal2" runat="server" Text="<% $SPUrl:~site/SiteAssets/ListOperations.js %>" />
<asp:literal ID="Literal3" runat="server" Text="' type='text/javascript' ></script>" />
Character Restrictions in Names of Projects and Project Items
Names of projects and project items 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 names of SharePoint projects and project items, 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 you're deploying contains only these valid characters.
Errors When Creating Custom Fields
In Visual Studio, custom fields are defined in XML. Errors can occur if a field isn't defined or referenced by using a specific format.
Error Message
“Invalid characters” error message at packaging time.
Resolution
The ID for a field definition must be a GUID surrounded by braces, as the following example shows:
<Field ID="{5744d18c-305e-4632-8bd1-09d134f4830d}"
Type="Note"
Name="PatientName"
DisplayName="Patient Name"
Group="A Custom Group">
</Field>.
As the following example shows, 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>):
<FieldRef ID="{5744d18c-305e-4632-8bd1-09d134f4830d}"
Name="PatientName"
DisplayName="Patient Name"
Required="TRUE"/>
If the source XML for the field is malformed, isn't a valid XML file, or exhibits some other problem, the error "Cannot parse file" occurs.
New Non-English Site Definitions Do Not Appear in Site Creation Page After Deployment
After you create and deploy a site definition by using a non-English version of Visual Studio (that is, a version with a locale ID other than 1033), the SharePoint Customizations tab doesn't appear in the Template Selection box and the new site template doesn't 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 on a clean system. A clean system is a computer that has a fresh installation of Visual Studio 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
In Solution Explorer, choose the workflow node.
In the Properties window, choose 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
In Solution Explorer, open the event receiver’s .feature file in the Feature Designer by either double-clicking the file or opening its shortcut menu and then choosing Open.
Choose the arrow next to Scope, and then choose Site in the list that appears.
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, choose the user control file, whose file name extension is .ascx.
On the menu bar, choose View, Properties Window.
In the Properties window, expand the Deployment Location node.
Ensure that the value of the Path property starts 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 projectfeaturename]\Files\Lists\[oldlist 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, choose the F5 key 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). You can avoid this problem 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 then choose the Application Pools node.
On the Application Pools page, choose the SharePoint application pool (typically "SharePoint - 80"), and then, in the Actions pane, choose the Advanced Settings link.
To increase the wait time before IIS timeout, change the value of Ping Maximum Response Time (seconds) to a value that's 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.
Choose the F5 key to run the solution.
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, deploy the solution by, on the menu bar, choosing Build, Deploy. (Don't debug the solution by choosing the F5 key.) 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 Debugging Starts
When you start to debug a SharePoint solution in Visual Studio, an error indicates that Visual Studio couldn't load the Web.config file because the given key wasn't 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 that's assigned to the Default Zone for the alternate access mappings of the web application. You can't resolve the error by using another zone, such as Intranet, for the URL. The site URL for the project and the URL in the default zone must match. To access alternate access mappings, open the SharePoint 2010 Central Administration utility, choose the Application Management link , and then, under Web Applications, choose the Configure alternate access mappings link. For more information, see Create zones for Web applications.
See Also
Concepts
Troubleshooting SharePoint Packaging and Deployment