Symptoms

The following appears in the atlassian-confluence.log:

2014-05-24 09:29:25,105 INFO [main] [confluence.upgrade.upgradetask.UserIndexingUpgradeTask] doUpgrade Beginning User Indexing repair.
2014-05-24 09:29:25,105 INFO [main] [confluence.upgrade.upgradetask.UserIndexingUpgradeTask] doUpgrade Retrieving the usernames and matching Personal Information from db...
2014-05-24 09:29:25,130 INFO [main] [confluence.upgrade.upgradetask.UserIndexingUpgradeTask] doUpgrade Found 775 usernames that need PersonalInformation reindexed.
2014-05-24 09:29:25,620 ERROR [main] [atlassian.confluence.upgrade.UpgradeLauncherServletContextListener] contextInitialized Upgrade failed, application will not start: Upgrade task com.atlassian.confluence.upgrade.upgradetask.UserIndexingUpgradeTask@591a5f3f failed during the UPGRADE phase due to: Unable to complete User indexing.
com.atlassian.confluence.upgrade.UpgradeException: Upgrade task com.atlassian.confluence.upgrade.upgradetask.UserIndexingUpgradeTask@591a5f3f failed during the UPGRADE phase due to: Unable to complete User indexing.
	at com.atlassian.confluence.upgrade.AbstractUpgradeManager.executeUpgradeStep(AbstractUpgradeManager.java:273)
	at com.atlassian.confluence.upgrade.AbstractUpgradeManager.runUpgradeTasks(AbstractUpgradeManager.java:228)
	at com.atlassian.confluence.upgrade.impl.DefaultUpgradeManager.runUpgradeTasks(DefaultUpgradeManager.java:382)

Diagnosis

1. Usually this error is triggered when there's a record in the user_mapping table with a null value in the lower_username column. That can be diagnosed by running the following query:

   SELECT * FROM user_mapping WHERE lower_username IS NULL;

   If the query returns any results then you will have to fix the data (outlined below) so that the upgrade can proceed. This error can also be triggered when Confluences searches for a user in the user_mapping table, and there is no corresponding record. To diagnose this, execute the SQL commands in the Resolution section to find out if the query in Step 3 returns any results. If so, those are the problematic records. 

2. This error also can occur when there is an uppercase or mixed case value in the lower_username column of the user_mapping table. Confluence is not able to find the user it's looking for because, for some reason, the value for lower_username contains uppercase characters (when it should be all lowercase), which doesn't match what Confluence is searching for. You can diagnose this by running the following query :

   select * from user_mapping where lower(username) != lower_username;

Cause

This error is triggered during the user indexing phase of the upgrade process, when Confluence queries the user_mapping table for users that are to be re-indexed. If Confluence encounters any null values during this phase it will throw a NullPointerException and the upgrade will fail. It can also throw a NullPointerException if it can't find any matches whatsoever (e.g., wrong casing for a value in the lower_username column).

There are two bugs that are tracking the root cause for this condition:

CONF-36018 - Getting issue details... STATUS

CONF-33706 - Getting issue details... STATUS

Resolution

There are a few resolutions depending on the cause. If you are affected by both null and mixed case values, perform these fixes in order (fix the nulls first).

Cause 1 - duplicate user_mapping entries with a null lower_username

1. Restore your pre-upgrade backups
2. Follow the workaround here: CONF-36018 - Getting issue details... STATUS
3. Try the upgrade again

Cause 2 - mixed case values in 'lower_username'

If there are values in the lower_username column that are actually mixed case, use the following command to fix those entries:

1. Shut down Confluence
2. Backup your database

3. Execute the following command: 

   update user_mapping set lower_username=lower(username) where lower(username) != lower_username;	

4. Restart Confluence