Troubleshooting Common Sharepoint Solution Installation Issues
Identifying the Root Cause
When a SharePoint solution fails to install properly, the first troubleshooting step is to identify the root cause of the failure. Carefully reviewing error logs and messages provides clues into the nature of the issue. Common installation failure causes include permission errors, missing prerequisites, retraction failures, and conflicts with existing solutions.
Reviewing Error Logs and Messages
The SharePoint ULS logs, Event Viewer, and administration web pages contain detailed error information generated during solution installations. Examine correlations IDs to match entries across different logs that relate to the same request. Error codes and descriptions reveal the type of failure, such as file not found exceptions or access denied errors when accessing resources. Errors also indicate which user identity or application pool account encountered the issue, pointing to permission problems.
Investigating Permission and Access Issues
Many SharePoint solution installation failures result from the solution installer account lacking necessary permissions. The app pool identity account requires read access to the solution files being installed. Review this account’s permissions on the file share storing the WSP solution packages. Also check the account’s access to the SharePoint content databases, especially if creating new site collections or webs.
Checking Prerequisites and Dependencies
Solution installations rely on certain prerequisites like application pools, IIS sites, managed paths, and language packs. Scan the installer logs for missing elements called out in the pre-requisites checks. Double check that all software and configuration dependencies detailed in the solution documentation are met prior to running the installer.
Fixing “File Not Found” Errors
“File not found” errors typically occur when a solution installer fails to locate a necessary component file on the filesystem at the specified location. Troubleshoot these file access issues by verifying file paths values, locations, permissions, storage availability and manually copying any missing files.
Verifying File Paths and Locations
Closely check the file paths configured in the solution setup and script files making sure directory names and mapped drive letters are correct. In particular, examine elements file paths for custom SharePoint components like mapped folders, images, style sheets and pages laid out in the manifest. Also confirm that referenced file servers, web URLs and database names align to the production environment.
Re-downloading Missing Files
If the solution manifest lists a required component file that appears to be present but cannot be accessed or loaded during installation, try downloading a fresh copy of the missing object. It may be that the existing file copy is locked, corrupted or overwritten. Extract component files from a known good copy of the solution package obtained from the software vendor.
Using PowerShell to Install Files
PowerShell scripts allow deploying SharePoint solution artifacts through code for precise control when facing access issues. Script commands can provision components into specific farm locations while handling permissions. PowerShell also offers rich logging capabilities to capture file operations tasks useful for troubleshooting file not found errors if they persist.
Resolving Access Denied Errors
Access denied errors while installing SharePoint solutions usually stem from identity and permissions misconfigurations on key folders, configuration databases or web applications themselves. Grant the proper access levels before re-attempting deployment. Also ensure the account runs under has not been denied access explicitly on part of the environment.
Confirming Account Permissions
The application pool identity and installer service accounts should have at minimum read access on solution files and folders and farm administrator rights. Validate that both accounts have these baseline permission assignments allowing access to enumerate and unpack solution files across servers. Also check that SQL database access roles are correctly applied especially when creating new site collections or webs.
Granting App Pool Identity Access
Many access denied errors trace back to the application pool identity account lacking permissions to deploy or activate solution files into SharePoint locations like the Global Assembly Cache (GAC). Temporarily assign this account Farm Admin privileges to rule out permissions then gradually reduce rights back down to the minimum roles of WSS_WPG, WSS_ADMIN_WPG, db_owner and db_securityadmin once installed.
Checking Folder and Library Permissions
Examine NTFS and SharePoint permissions on key folders like the Solution store, Web application templates and the 14 root hive. If the solution creates new site collections or document libraries, check the identity has Creator Owner rights on the respective Web application or parent site. Custom solutions may require temporary broader access to write out page templates, master pages, style sheets and Silverlight components.
Debugging Solution Retraction Failures
At times SharePoint solutions fail to properly retract or uninstall after deploying successfully initially. Diagnosing the specific cause requires logging every action during retraction and comparing the environment before and after. Also leverage verbose command-line logging and correlation IDs to piece together the events.
Enabling Verbose Logging
Retracting SharePoint solutions through the GUI generates limited logs often lacking enough details on the steps and failures. Enable verbose PowerShell logging by adding -Verbose switches to Uninstall-SPSolution and Remove-SPSolution. Pipe the streams to log files for post-analysis. Errors output include refusal to retract unmanaged or uninstalled solutions, scope conflicts and timing issues.
Examining Correlation IDs
SharePoint assigns unique correlation IDs to every request for tracking operations across multiple components. Monitor these GUIDs in the verbose PowerShell logs during solution retraction. Also find matching entries stamped with the same correlation ID in the ULS logs and Developer Dashboard for insights into associated events such as remaining ghost references.
Comparing Before and After States
Diff the SharePoint environment at file system, database and operational levels before and after attempting to retract the troublesome solution. Checks for differences in web.configs, registry keys, application pool recycling, app domain restarts, remaining service instances, PowerShell snap-ins or timers provide clues on failed retractions. Any components not cleaned up indicate the root cause.
Avoiding Conflicts with Existing Solutions
Deploying a SharePoint solution that overlaps with functionality or resources of an already installed package leads to conflicts often blocking activation or causing farm instability. Avoid these issues by planning scope, validating interoperability, properly retracting previous solutions and testing rigorously.
Understanding Scope and Overlaps
Thoroughly document both architecture and implementation details for existing solutions in the target farm. Next map out all elements planned for the incoming solution searching for any intersections including custom databases, web templates, managed paths, feature stapling, event receivers and branding artifacts. Refactor one solution to eliminate overlaps before attempting dual deployments.
Retracting Solutions Cleanly
Use the STSADM or PowerShell cmdlets to properly uninstall rather than directly deleting solution files or components of an existing package that conflicts with a newly deployed one. First retract the customizable SharePoint pieces safely then remove the solution entirely from the farm rather than risking leftovers blocking a clean activation of the incoming solution.
Testing in Staging Environments
Replicate the production SharePoint environment including all existing solutions for testing the deployment of incoming solutions safely in staging farms. Validate scope, functionality and interoperability prior to attempting concurrent solution activations in live production which carries substantial business risk if conflicts emerge post-deployment.
Optimizing Performance for Large Solutions
As a SharePoint solution grows to hundreds of features, entity schemas and custom code the cumulative resource demands also increase. Avoid farm performance hits or timeouts by optimizing delivery of large packages through caching, modularization and proper testing at scale.
Leveraging Caching and CDNs
Configure object caching on web front ends and distributed caching via AppFabric to reduce database queries triggered by complex solutions. Offload static solution resources like images, scripts and stylesheets onto a content delivery network (CDN) to lower network latency and web server processing loads when rendering performance-intensive pages.
Enabling Object Cache Accounts
To utilize caching, the SharePoint cache cluster and object cache user accounts must have access to query Active Directory for identity lookups. Enable these hidden accounts by checking the boxes titled “Register account with Active Directory” under the custom object cache settings in Central Admin. Retry cache-dependent solutions after verifying caching remains active.
Breaking Up Solutions into Modules
Deconstruct a large monolithic SharePoint solution into multiple smaller interdependent solutions around logical functionality areas which align teams, development lifecycles and deployment cadences. Separate solutions activate faster, fail isolation, can retract independently and enable phased rollouts to manage risk as modules get deployed into production individually.
