Background

When using the Jira Cloud Migration Assistant to migrate Software projects or users and groups, you may encounter warnings or errors thrown by the application that require you to take some action. This document provides some basic troubleshooting steps for common migration errors.

Environment

• Jira Cloud Migration Assistant 1.0 or greater

How to download migration errors

You'll be notified of errors after the migration has run. The migration status will show as Incomplete.

To download detailed error logs:

This will download a zip file containing a .log file which will contain the errors in the attempted migration.

How to troubleshoot error messages

Error Message

ERROR YYY project-import We couldn't import Permission Scheme 'XYZ scheme'.

Reason: IllegalStateException: Errors: {holder.parameter=User 'user.name' does not exist}

Description

There are permission schemes associated with the selected projects in your migration that reference invalid, or missing users. These users are often located in out of date accounts in your Crowd or External Identity Provider (IDP) that were never migrated across to begin with.

Fix

1. Remove the referenced user from named permission scheme in your server/DC instance.

2. See this help document on how to remove or delete users from permission schemes.

3. Re-run migration through the Jira Cloud Migration Assistant

Error Message

ERROR YYY project-export We couldn't export Work Log XXXXX.

Reason: java.lang.IllegalArgumentException: MRI entity id must not be blank.

Description

There are blank values in worklog tables that are not compatible with our cloud database constraints. This can happen in on-premise due to this behaviour .

Fix

Error Message

ERROR YYY project-import We couldn't import Screen 'XYZ Screen Name'.

Reason: IllegalArgumentException: Tab name must not be blank.

Description

There are blank screen names in Jira.

Fix

Find the blank screen tabs and update them with names through the UI.

1. Go to Screens in Jira

2. Find screen affected in error log

3. Click on Configure

4. Find the blank Screen tab

5. Add a name to any blank tabs

6. Re-run migration through Jira Cloud Migration Assistant

Error Message

ERROR YYY project-import We couldn't import Field Layout Item XXXXX-customfield_XXXXX.

Reason: Field customfield_XXXXX does not exist in FieldLayout XXXXX.

ERROR YYY project-import We couldn't import Project YYY.

Reason: IllegalArgumentException: Issue type scheme [XXXXX] does not exist.

ERROR YYY project-import We couldn't import Project YYY.

Reason: IllegalArgumentException: Workflow scheme [XXXXX] does not exist.

ERROR YYY project-import We couldn't import Issue YYY-XXXX.

Reason: NullPointerException: There is no step in workflow [workflow] linked to status [status].

Description

Previously migrated entities have been updated or removed from the source or destination sites, causing breakages. Read about how the Jira Cloud Migration Assistant migrates your data here.

Fix

There are two ways to mitigate this problem.

• If you have run into this problem on a test site, consider resetting your migration by wiping the target cloud site and starting again. This document explains the wipe process in greater detail.

Or

• If you are unable to reset the target site, contact Atlassian Support.

Error Message

ERROR YYY project-export We couldn't export Project Role 'Role_name'.

Reason: java.lang.IllegalArgumentException: Reference "role_name" is not a group reference.

ERROR YYY project-import We couldn't import Project Role Association XXXXX.

Reason: IllegalArgumentException: Project role [XXXXX] does not exist

Description

These errors are going to indicate that the projects in your migration have roles or permission schemes which reference groups or roles that no longer exist.

Fix

There are two ways to mitigate this problem.

• Re-create these roles or groups so that they exist on the Source server before running the migration again.

Or

• Edit the project's permissions to remove any references to these roles or groups before running the migration again.

This document explains in further detail how to edit permissions and roles in your Jira projects.

Error Message

ERROR YYY project-export Board 'YYYY' is shared to users of other projects: group_name

Please remove these share permissions and re-create them after migration.

Description

There is a board in your migration that is shared with groups not included in your migration.

Fix

We need to modify the shared filters in the board to remove this reference

1. Go to the boards mentioned in the error log

2. Click on Board → Configure

3. Under General and Filter → Edit Filter Shares

4. Remove users or groups that were referenced in the error log from the affected board

5. Re-run migration through the Jira Cloud Migration Assistant

Error Message

ERROR YYY project-import We couldn't import Issue YYY-XXX.

Reason: Issue can be assigned to only closed sprints, and one active or future sprint during migration..

Description

There is a mismatch between the target site and the source sprint.

• You are remigrating a project to cloud that contained a Sprint that was active but is no longer.

• The project was deleted in the cloud, but the Sprint was not deleted when the project was being deleted.

• The project was migrated to cloud again.

Fix

1. Remove the issues from the sprint in the source site and re-run your migration.

2. Close the sprints on server but active on the cloud and try migrating again.

3. Follow the article Delete a Sprint in Jira Cloud to delete these migrated Sprints from the cloud site.

Error Message

ERROR YYY project-export Notification Scheme - [Default Notification Scheme] with id - [10000] has missing reference to group - [BBB-group]. Verify if group - [BBB-group] is valid.

Description

This can occur if the notification scheme in migration scope has references to a group that no longer exists.

Fix

1. Go to Settings > Issues.
2. Scroll to "Notification schemes".
3. Next to the named notification scheme, click on "Notifications" in the Action column.
4. Search for references to the "BBB-group" group and click the "Delete" link.
5. Repeat this for all references to "BBB-group". This will remove all references to this non-existent group.
6. Re-run migration through Jira Cloud Migration Assistant

Error Message

We couldn't import Issue Watcher Association XXXX.

Reason: Insertion of IssueWatcherAssociations did not complete

Description

This error can be replicated if multiple users are sharing the same e-mail address in your source instance.

Fix

1. Check for duplicates by running the below SQL on your Server instance.

   select lower_email_address,count(lower_email_address) from cwd_user group by lower_email_address having count(lower_email_address) > 1

2. Remove one or update one of the users emails so they are unique.
3. Re-run migration through Jira Cloud Migration Assistant

Error Message

We couldn't import Issue Watcher Association XXXX.

Reason: Insertion of IssueWatcherAssociations did not complete

Description

This error can be replicated if multiple users are sharing the same e-mail address in your source instance.

Fix

1. Check for duplicates by running the below SQL on your Server instance.

   select lower_email_address,count(lower_email_address) from cwd_user group by lower_email_address having count(lower_email_address) > 1

2. Remove one or update one of the users emails so they are unique.
3. Re-run migration through Jira Cloud Migration Assistant

Error Message

We found some email addresses that are connected to multiple users. To migrate, all users will need to have a unique email address.

Click on the user number to see which users the email is connected to.

Description

 Each user must have a unique email (case insensitive). If the Jira Cloud Migration Assistant detects multiple users with the same email, either in the Jira user tables or your synced identity provider, this error will be shown.

Fix

1. You can either update the emails of the users to be unique or remove them entirely from your site or identity provider.

2. Follow these instructions on how to remove or edit user emails in your Jira Software server instance.

3. Re-run migration through the Jira Cloud Migration Assistant.

Tip: If you've got large numbers of users and checking for duplicates in the UI is not feasible, run the SQL below on your source instance to retrieve email addresses referenced more than once in your user table.

select lower_email_address,count(lower_email_address) from cwd_user group by lower_email_address having count(lower_email_address) > 1

SELECT s.filtername, s.authorname as owner, s.reqcontent as jql, s.DESCRIPTION,sp.entityid, sp.sharetype, sp.PARAM1 FROM searchrequest s JOIN sharepermissions sp ON sp.entityid = s.ID WHERE sp.entitytype = 'SearchRequest' ORDER BY filtername;

SELECT filtername, authorname as owner, reqcontent as jql, DESCRIPTION FROM searchrequest WHERE ID NOT IN (SELECT entityid FROM sharepermissions WHERE entitytype = 'SearchRequest') ORDER BY filtername;

select * from (select t.*, jw.workflowname,  unnest(xpath('//action[@name="' || t.action || '"]/results/unconditional-result/post-functions/function/arg[@name="class.name"]/text()', 
             (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as post_function_class from jiraworkflows jw
             join (select id, unnest(xpath('//*/action/@name',  (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as action from jiraworkflows) t on t.id = jw.id ) a where post_function_class::text not like 'com.atlassian.jira%'

select * from (select t.*, jw.workflowname,  unnest(xpath('//action[@name="' || t.action || '"]/validators/validator/arg[@name="class.name"]/text()', 
             (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as validators from jiraworkflows jw
             join (select id, unnest(xpath('//*/action/@name',  (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as action from jiraworkflows) t on t.id = jw.id ) a where validators::text not like 'com.atlassian.jira%'

select * from (select t.*, jw.workflowname,  unnest(xpath('//action[@name="' || t.action || '"]/restrict-to/conditions/condition/arg[@name="class.name"]/text()', 
             (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as conditions from jiraworkflows jw
             join (select id, unnest(xpath('//*/action/@name',  (regexp_replace(descriptor, '\<\![^\<]+\>', ''))::xml)) as action from jiraworkflows) t on t.id = jw.id ) a where conditions::text not like 'com.atlassian.jira%'

select * from notificationscheme;

SELECT * FROM "AO_60DB71_CARDCOLOR" WHERE color IS NULL OR val IS NULL OR strategy IS NULL;