Troubleshooting errors and non-migrated entities with the Jira Cloud Migration Assistant

Still need help?

The Atlassian Community is here for you.

Ask the community

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

Always back up your data before performing any modifications to the database. If possible, test any alter, insert, update, or delete SQL commands on a staging server first.

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:

Click "View details" from the Migrations dashboard

Click the "Download error logs" link on the Migration screen


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

We need to find which rows have blank values and update them to be NULL instead.

  1. First, run the below SQL statement.

    select * from worklog
  2. Pay attention to the `grouplevel` column in the Worklogs table.

  3. If there are non-null blank characters run the follow SQL to update them

    update worklog set grouplevel=null where grouplevel = "";
  4. Re-run migration through the Jira Cloud Migration Assistant


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


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 BoardConfigure

  3. Under General and FilterEdit 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

We couldn't import Issue Watcher Association XXXX.

Reason: Insertion of IssueWatcherAssociations did not complete

Description

This can occur if there are multiple users with the sharing the same email 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


How to reconcile and re-create entities that the Migration Assistant does not support

Some entities are not yet supported for migration through the Jira Cloud Migration Assistant. The full list of entities are detailed in this document.

Dashboards and Filters

Team dashboards/filters, these are currently not supported by the Jira Cloud Migration Assistant. This means, they must be manually re-created on the cloud side.

For filters, you can get the list of shared filters, with their permissions, using the following SQL query on your server instance:

Click for SQL...
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;

The following query can also be used to find private filters:

Click for SQL...
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;

Custom fields

The following custom fields are not supported by the Jira Cloud Migration Assistant:

  • Single and Multi-version picker

  • URL

  • Select List (cascading)

  • Select List (multiple choice)

  • Project picker 

Use the CSV importer to bring across just the custom field values associated to issues in your migration. Further instructions explained at the bottom of this document.


Workflow functions

Non-native Jira Workflow Functions are currently not supported by the Jira Cloud Migration Assistant. This means, they must be manually re-created on the cloud site if you’d like to continue using them.

  • Post Function: clear field value, update custom field, copy value from other field, delegating

  • Validator: required field, field changed

  • Condition: user in group, in project role, field value, subtask blocking

You can run these SQLs on your server instance to help check which workflows may be affected pre-migration.

Check for Post-functions not native to the cloud in the migrated workflows. (Add-ons and apps etc)

Click for SQL...
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%'

Check for Validators not native to the cloud in the migrated workflows. (Add-ons and apps etc)

Click for SQL...
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%'

Check for Conditions not native to the cloud in the migrated workflows. (Add-ons and apps etc)

Click for SQL...
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%'

Notification schemes

Run the SQL below to get the details of notification schemes in your server instance. Any non-default notification schemes will need to be recreated on the cloud site.

select * from notificationscheme;

Mail handlers

You will need to recreate these on the target cloud site after migration. Read this document to reconfigure your mail handlers.

Project avatars

No known workaround - you'll need to re-add these to your target cloud site manually.

Links to issues or entities that are not migrated

  • Jira Remote Links are not yet supported - these will need to be re-built.
  • Issue links between projects will appear once all dependant project and issues have been migrated.

Custom field language translations

No known workaround - you'll need to re-add these to your target cloud site manually.

More information and support

We have a number of channels available to help you with your migration.

Last modified on Feb 8, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.