Troubleshoot and resume upgrade (Windows SharePoint Services)

Applies To: Windows SharePoint Services 3.0

 

Topic Last Modified: 2009-02-05

In this article:

  • General information about troubleshooting and restarting upgrade

  • Known issues for pre-upgrade scanning

  • Known issues for in-place upgrade

  • Known issues for gradual upgrade

  • Known issues for database migration

  • Known issues for customized sites

General information about troubleshooting and restarting upgrade

If upgrade stops, you can use the following methods to troubleshoot the issues:

  • Look for the word "error" in the upgrade log files. The upgrade log files are located at %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\LOGS. For more information about viewing the upgrade log, see Verify upgrade (Windows SharePoint Services).

    Tip

    Use the Search Files and Folders feature of Windows to find iterations of “error” quickly in these log files.

  • Review the events in Event Viewer and look for any application errors.

  • Review the readme file for known issues and workarounds. Errors are often issues that you can work around.

  • If you are running Gradual Upgrade, check to see if the site collections you were running have appeared in the new version. If so, you can perform the workaround there, or revert the v3 site to v2, and try to upgrade the site again. For more information about reverting sites, see Revert to a previous version site (Windows SharePoint Services).

  • In-place upgrade can be restarted using the command stsadm –o upgrade. Upgrade will skip those tasks that were already complete, and continue from where it left off. For more information about the upgrade operation, see Upgrade sites (Windows SharePoint Services).

Known issues for pre-upgrade scanning

Upgrade is blocked if you use Localhost as your server name

Using "localhost" as your server name can cause many issues in your environment and is not recommended. If you are using "localhost" as your server name, when you run the pre-upgrade scan tool, this issue is logged and the upgrade cannot proceed. You must rename the server computer and then run an operation in prescan before you can continue with the upgrade. Follow the steps below to rename your server and fix the issue for the pre-upgrade scan tool.

  1. Back up the configuration database.

  2. From the command line, change to the following path: %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\60\bin, and then run the following command to change the server name in the configuration database:

    Stsadm.exe -o setconfigdb -databaseserver <server name> -connect

  3. From the command line, change to the following path: %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\bin, and then run the following command to clear the issue for the pre-upgrade scan tool:

    Prescan /fixlocalhost

  4. On the command line, run the following command to re-run the pre-upgrade scan process:

    Prescan /all

    • If it is successful, proceed with upgrade.

    • If it still fails, then there is still a service using the localhost servername. At this point, upgrade is not blocked, but some services may not upgrade successfully.

Known issues for in-place upgrade

You must use a domain account, not Network Service, for server farm upgrades

For either in-place or gradual upgrade in a server farm environment, you should use the same credentials that you used in the version 2 environment in your version 3 environment. However, if you were using the Network Service account for your version 2 environment, you must instead use a domain account in version 3. Your version 2 environment can continue using Network Service, but when you install version 3 and create the new farm, you must supply a domain account instead. Be sure that you grant the domain account that you use the appropriate rights to the databases in SQL Server (must be a member of the database creators, process administrators, and database owners group for all version 2 databases).

Some settings are not preserved on the Web application when you perform an in-place upgrade

If you use Secure Sockets Layer (SSL) and perform an in-place upgrade, you must use the Alternate Access Mapping (AAM) feature to modify the URL within Windows SharePoint Services because some settings are not preserved on the Web application.

Before you upgrade, if you have an AAM entry that uses HTTPS, such as the following:

Incoming URL: https://<server name>

Outgoing URL: https://<server name>

After you perform an in-place upgrade of Windows SharePoint Services 3.0, this entry will be incorrectly set to:

Incoming URL: https://<server name>

Outgoing URL: http://<server name>

To correct the URL, on the SharePoint Central Administration Web site, on the Operations page, click Alternate Access Mappings, and then click Edit Public URLs to set the URL back to:

Incoming URL: https://<server name>

Outgoing URL: https://<server name>

For more information about alternate access mappings, see Plan alternate access mappings (Windows SharePoint Services).

Upgrade finishes on the first front-end Web server but has failures

In a farm that uses multiple front-end Web servers, if the upgrade finishes on the first front-end Web server but has failures, we recommend that you solve the problem and rerun the upgrade before you move on to upgrade any additional front-end Web servers.

If, for some reason, you want to disregard the failure (for example, because the failure has to do with a rarely used site collection), you can move on to upgrade the second front-end Web server by using the Psconfig command-line tool. Use the following command-line operation:

Psconfig -cmd upgrade -inplace b2b -wait -force

Note

You cannot use the SharePoint Product and Technologies Configuration Wizard to upgrade additional front-end Web servers if you use the Psconfig command-line tool.

SPConfigurationDatabase2 sequence error in the upgrade log

If you perform an in-place upgrade and it fails, check Upgrade.log, which is located in the COMMONPROGRAMFILES%\Microsoft Shared\Web server extensions\12\LOGS folder. If you receive the following error message: “[SPConfigurationDatabaseSequence2] [ERROR] [date]: The role 'WSS_Content_Application_Pools' already exists in the current database,” you can use any of the following workarounds to solve the problem:

  • Run the following SQL queries on the configuration database.

    delete from dependencies

    delete from objects

    delete from classes

    delete from sitemap

    exec sp_droprole N'WSS_Content_Application_Pools'

    Note

    If the drop role has any members when the action failed, the sp_droprole call returns the names of those members. You must then run the following command for each member.

    exec sp_droprolemember N'WSS_Content_Application_Pools',

    N'usernameReturnedFromSP_DropRole'

    Then you must run the following query again.

    exec sp_droprole N'WSS_Content_Application_Pools'

  • Create a new V3 farm, and then attach the existing content database. This option will retain all the user data, but will lose configuration information that was stored in the V2 configuration database, such as Web Part packages and virtual server settings.

  • If the original failure was addressed (for example, the failure was due to lost network connectivity or insufficient SQL Server computer disk space and then corrected), you can restore the V2 farm and then restart the upgrade.

Note

Remember to restart the upgrade after you have performed the workarounds.

For in-place upgrades on stand-alone servers, run upgrade from the command-line if you get an error with a login failure or connection failure to the database

If you are running an in-place upgrade on a stand-alone server running WMSDE, the upgrade process might time out and generate an error similar to the following:

SPContentDatabaseSequence] [ERROR] [10/18/2006 12:42:44 PM]: Cannot open database "STS_DATABASE_NAME_1" requested by the login. The login failed.

Login failed for user 'NT AUTHORITY\NETWORK SERVICE'.

[SPContentDatabaseSequence] [ERROR] [10/18/2006 12:42:44 PM]: at System.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection)

at System.Data.SqlClient.TdsParser.ThrowExceptionAndWarning(TdsParserStateObject stateObj)

If you see this error, or an error about a database connection failure, you must use the command-line to complete the upgrade.

  1. Open a command prompt window and change to the following directory: %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\bin

  2. Run the following command to resume and complete upgrade:

    psconfig -cmd upgrade -inplace v2v -force -wait

For more information about using the psconfig.exe command-line utility, see Command-line reference for the SharePoint Products and Technologies Configuration Wizard (Windows SharePoint Services).

Known issues for gradual upgrade

You must use a domain account, not Network Service, for server farm upgrades

For either in-place or gradual upgrade in a server farm environment, you should use the same credentials that you used in the version 2 environment in your version 3 environment. However, if you were using the Network Service account for your version 2 environment, you must instead use a domain account in version 3. Your version 2 environment can continue using Network Service, but when you install version 3 and create the new farm, you must supply a domain account instead. Be sure that you grant the domain account that you use the appropriate rights to the databases in SQL Server (must be a member of the database creators, process administrators, and database owners group for all version 2 databases).

Additional steps are required to gradually upgrade an SSL-only servers

The gradual upgrade process uses a paired set of IIS Web sites to host the original (un-upgraded) site and new (upgraded) site. By default, the new site that is created does not use SSL. If you need this Web site to use SSL, you must perform additional steps during the gradual upgrade process to set the IIS settings and port number to be correct for SSL.

Perform the following steps after you have created the target Web application for your sites, but before you upgrade any sites.

For more information about creating the target Web application, see Create a new Web application to host upgraded sites in Upgrade sites (Windows SharePoint Services)).

Change the port numbers and SSL settings in Internet Information Services (IIS) Manager

  1. In Internet Information Services (IIS) Manager, click the plus sign (+) next to the server name that contains the Web application you want to change.

  2. Click the plus sign (+) next to Web sites.

  3. Right-click Default Web Site, and then click Properties.

  4. On the Web Site tab, in the SSL port box, type 444, and then click OK.

  5. Right-click Default Web Site_Pair, and then click Properties.

  6. On the Web Site tab, in the SSL port box, type 443, and then click Apply.

  7. On the Directory Security tab, in the Secure communications section, click Server Certificate.

    Follow the steps in the wizard to assign a new certificate.

  8. On the Directory Security tab, in the Secure communications section, click Edit.

  9. In the Secure Communications dialog box, select the Require secure channel (SSL) check box, and then click OK.

  10. Click OK to close the Default Web Site_Pair Properties box.

Update alternate access mapping settings and reset IIS

  1. Open a command prompt window and change to the following directory: %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\12\bin.

  2. Run the following command to change the alternate access mapping for the original Default Web Site to point to port 444:

    Stsadm -o addzoneurl -url https://server_name:port -urlzone default -zonemappedurl https://server_name:444

    Where server_name:port is the location for the Default Web site.

  3. Change to the following directory: %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\60\bin.

  4. Run the following command to change the alternate access mapping for the redirected Web site:

    Stsadm -o addzoneurl -url http://server_name:port -urlzone default -zonemappedurl https://server_name:443

    Where server_name:port is the location for the new site that was created when you created the target Web application.

  5. Run the following command to reset IIS:

    iisreset /noforce

I finalized the upgrade, but some sites were not upgraded yet, what can I do?

If you have finalized the upgrade process, you can no longer use the gradual upgrade method to upgrade any remaining sites. You can, however, use the database migration approach to upgrade the sites. For more information about using database migration to upgrade sites after having finalized a gradual upgrade, see article 926718 in the Microsoft Knowledge Base (https://support.microsoft.com/kb/926718).

I have selected the “Do not upgrade” option in the Setup screen, but I have now changed my mind and want to upgrade

If you have selected the Do not upgrade option during Setup and change your mind after you run the SharePoint Products and Technologies Configuration Wizard, you must run the SharePoint Products and Technologies Configuration Wizard again to change to a gradual upgrade.

Use the SharePoint Products and Technologies Configuration Wizard to change from the “Do not upgrade” option to a gradual upgrade

  1. Run the SharePoint Products and Technologies Configuration Wizard to disconnect from the farm.

  2. Go to %COMMOMPROGRAMFILES%\Microsoft shared\Web Server Extensions\12.0\WSS\ and change the registry key to V2V_GRADUAL_UPGRADE for SetupType and SetupTypeBackup.

  3. Rerun the SharePoint Products and Technologies Configuration Wizard to perform the upgrade.

Known issues for database migration

You cannot add the same content database more than once to a farm, even on different Web applications

Each site collection in a content database (including each portal site) has a globally-unique identifier (GUID) associated with it, registered in the configuration database. So, adding the same site collection (or portal) twice to the farm, even in separate Web applications, is not possible. Although the database attach succeeds in this situation, the site collection cannot be started. If you need a duplicate copy of a site collection (or portal) in the same farm, first attach the database that contains the site collection to a separate farm, and then use the Stsadm.exe backup and restore operations to copy the site collection over to the other farm. The backup and restore process creates a new GUID for the site collection.

Known issues for customized sites

An application error can result when disallowed customizations are made to Web.config files

Certain customizations are not allowed in Web.config files for subfolders within a virtual server. For example, the AUTHENTICATION and SESSIONSTATE nodes are not allowed within the Web.config file at this level. Modifying the Web.config file in ways that are not recommended can result in unexpected upgrade results. Be sure to follow the recommended practices for customizations, including customizations to the Web.config file. For more information, see Best Practices for Ensuring Application Reusability and Upgrade in Windows SharePoint Services on the MSDN Web site (https://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc\_SP2003\_ta/html/WSSSharePointCodeReuse.asp).

Download this book

This topic is included in the following downloadable book for easier reading and printing:

See the full list of available books at Downloadable books for Windows SharePoint Services.