• Products
  • Documentation
  • Resources

Troubleshoot migration with Jira Cloud Migration Assistant

This page will help you troubleshooting problems that you might encounter when using the Jira Cloud Migration Assistant.

How to use this page

Press Ctrl+F or Command+F (on a Mac) on this page and enter the error message details into the find field to look for the relevant KB article.

We’ve divided this page into a few categories, depending on where you are in your migration journey:

  • Known issues

  • Before you run the migration

  • After you run the migration

  • How to contact Atlassian support

Known issues

Here’s a list of known issues that might affect your migration or the already migrated data.

Topic

Description

Data integrity

If your Jira Server site is highly customized, you may face additional issues when migrating. For example, if you have any required field with a null value the migration will fail because this is not supported on your Cloud site. We recommend cleaning up your instance data before migrating.

Incomplete migrations and projects

An incomplete status means that some things have been migrated but there was at least 1 entity that we couldn’t migrate. For example, we might be able to migrate a project but 1 issue fails because there is a null value in a custom field. In this case, the project will show up as incomplete even though all the actual data is complete. Many times this status will not be a problem for your migration. Download the error logs to determine what is causing the failure. 

Changes on Server before migrating

If you make any changes on your Server site, wait at least 10 minutes before migrating to allow all data to be updated. 

Changing project keys

If you choose to change a project key on your Server before or during migration, make sure that all configuration, filters and boards are updated with the new project key before attempting a new migration. 

Links to projects and issues that aren’t included in the migration

If you have chosen to migrate in smaller batches, links to projects or issues that haven't yet been migrated will be missing until that linked item is migrated. 

History entries with missing references

If a history entry refers to a missing link or attachment, the history entry won't be migrated. If a linked issue or project is migrated at a later date, the history entry will be updated. 

Jira boards not returning correct results

The migration assistant does not check that  the JQL issue filters on boards are returning the correct results after migration. If a board has a filter that mentions a project or field that is not yet migrated, the board may not return the same results after it is migrated. To fix this issue, edit the board's JQL filter after migrating. Learn more about board filters

Problems with Jira Align after the migration

If you use Jira Align, you need to complete additional steps before, during, and after the migration. If you’re having problems, see the linked page or contact Atlassian Support. Learn how to migrate Jira Align

Before you run the migration

There are two things you can check before running the migration:

  • Pre-migration checks

  • Pre-migration report

Pre-migration checks

Pre-migration checks are a mandatory step of every migration. They make sure that your configuration is correct and that the data can be migrated to Cloud. Run pre-migration checks, review, and run a Jira migration

Checks statuses

Here’s a brief description of statuses shown by pre-migration checks.

Symbol

Description

check successful

The check has passed. You can proceed with your migration.

Expand the warning message to view details and relevant links

You can proceed with your migration, but you need to be aware of a potential issue. Expand the warning messages to view details.

Expand the error message to view details and relevant links.

You can’t proceed with your migration until you resolve the error. Expand the error messages to view details.

Refresh the checks to try again or contact support if you continue to get this message

The check wasn’t completed due to an unexpected error. Refresh the checks or contact Atlassian support.

Common problems shown by checks

Here are common problems shown by checks and steps you need to take to solve them.

Message

Fixes / KB articles

We are currently updating the migration service

The Jira Cloud Migration Assistant authentication token might have expired.

Learn how to renew your authentication token

We couldn’t check for users count limit

The Jira Cloud Migration Assistant authentication token might have expired.

Learn how to renew your authentication token

We couldn’t check for projects in your cloud site

The Jira Cloud Migration Assistant authentication token might have expired.

Learn how to renew your authentication token

We couldn’t check for projects in your cloud site

It’s possible that your cloud site is unavailable for migration. Here are the reasons and fixes:

Reason 1: Your sandbox has been deleted.

Fix:

  1. Check if your sandbox is deleted:

    1. Go to admin.atlassian.com, and then select your organization if you have more than one.

    2. Select Products > Sandbox.

  2. If deleted, contact support for further assistance.

Reason 2: Your cloud site couldn’t be found or your Jira Cloud subscription has been deactivated due to inactivity.
Fix:

  1. Check if your cloud site subscription is canceled:

    1. Go to admin.atlassian.com, and then select your organization if you have more than one.

    2. Select Billing.

  2. If canceled, recover the canceled site.

Projects already exists in your cloud site

Project Name and Project Key Conflict When Migrating Using Jira Cloud Migration Assistant (JCMA)

Multiple users have the same email address

Fix duplicated email addresses

Invalid email addresses

Fix invalid email addresses

You’ve reached the limit of email aliases for a single email address

This check is shown when the number of email aliases related to a single primary email exceeds the limit of 10. An alias is a variation of the primary email, for example charlie+suffix@atlassian.com vs. charlie@atlassian.com.

The limit exists on the cloud side and allows to create only 10 aliases per hour.

Download CSV file

When viewing the check, you can download a CSV file to help you resolve the issue. The file:

  • Lists all email aliases (including the first 10) for cases where the limit was exceeded. It might include aliases related to multiple primary emails.

  • Doesn’t include the primary email itself.

Goal

Your goal is to change the aliases into individual emails or delete the corresponding users. It’s enough if you do it for aliases that exceed the limit. However, since cloud subscriptions are billed per user, you might want to delete or deactivate these extra users.

Solve the issue

To solve this issue, use the CSV file to identify the corresponding users and either update or delete them:

  • If you manage users in Jira, you can update them in Administration > User management.

  • If you manage users in an external directory, we recommend that you update users in the directory so the aliases aren’t provisioned to cloud.

Data preparation errors

Here are errors related to the Data preparation check and steps you need to take to solve them. They are recorded in the log file (downloadable ZIP file).

Error Code

Error

Fixes / KB articles

JCMA 124

ERROR [JCMA 124] <project key> project-export: The board ‘<board name>’ is assigned invalid administrators: ‘<group name>’.

To assign valid administrators to your board:

  1. Open the board for which you want to assign administrators.

  2. Go to Board > Configure.

  3. In the Administrators field, hover over to click the edit icon.

  4. Remove the invalid groups mentioned in the error log.

  5. Enter the names of the users or groups. If you start typing the name, a list of users and groups will be suggested.

  6. Press the Enter key when finished.

JCMA 149

ERROR [JCMA 149] <project key> project-export: The issue type ‘<issue type name>’ with issue key ‘<issue key>’ has no ‘<issue status>’ status in workflow ‘<workflow name>’.

To assign valid status:

  1. Select Settings > Issues

  2. Under WORKFLOWS, click Workflow Schemes.

  3. In the Workflow column, look for the affected workflow.

  4. Open the workflow to view the list of valid statuses in the Linked Status column.

  5. Open the issue for which the invalid status was assigned.

  6. From the Workflow list, select a valid status.

JCMA 510

ERROR [JCMA 510] <projectKey> project-export Couldn't migrate Request Type with id <requestTypeId> linked to Issue Type with id <issueTypeId>

Add the Issue Type with id <issueTypeId> to the Issue type Scheme of the project with id <projectId> to resolve

You can perform step A and step B to fix this error.

Step A: Make a list of issue types used for the request types of the Jira Service Management project.

To make a list:

  1. In Jira Server or Data Center go to Settings > Projects.

  2. Search for the Jira Service Management project for which the error was found.

  3. Click to open Project settings screen.

  4. Select Request types.

  5. From the Issue type column, list down all the issue types. For example, Task, Service request etc.

Step B: Check and add the issue types that are missing from the Issue Types for Current Scheme list based on the issues types list from step A.

To add the missing issue types:

  1. Go to Settings > Issues.

  2. From the left panel, select Issue type schemes.

  3. For the relevant issue type scheme of the Jira Service Management project, select Edit.

  4. Drag the missing issue type from Available Issue Types to Issue Types for Current Scheme.

  5. Click Save.

After step A and step B, you can retry your migration.

JCMA 147

ERROR [JCMA 147] <project key> project-export: The Kanban / Scrum board '<board name>’ cannot be linked to the Business project ‘<project name>’ on cloud.

ERROR XXX project-export KANBAN/ SCRUM board [XXXX] cannot be linked to business project [XXX] on Cloud.

JCMA 151

ERROR [JCMA 151] <project key> project-export: The workflow ‘<workflow name>' with transition '<transition name>’ is linked to an invalid screen.

To assign a valid screen to the workflow transition:

  1. Select Settings > Issues

  2. Under WORKFLOWS, select Workflows.

  3. Look for the affected workflow name, and select Edit.

  4. In the diagram, select the affected transition.

  5. On the right-hand side of the screen, select Edit to change the screen name.

  6. Select Save.

  7. Repeat steps 4 through 6 to fix multiple transitions.

JCMA 701

ERROR CROSS-PROJECT-DATA project-export Exception Message generated on executing query for fetching arPlanPermissions -> <exception message>
Exception Cause -> <exception cause>

Use the following KB articles to resolve the error:

JCMA 152

ERROR <project key> project-export Issue <issue type> has invalid issue type.

To assign an issue type:

  1. Go to Projects.

  2. Open the project for which you want to add the issue type.

  3. Select Project Settings.

  4. Under Issue types, select the issue type scheme.

  5. Go to Actions > Use a different scheme.

  6. Select Create a new scheme and associate with current projects.

  7. Add all the relevant issue types from available issue types.

  8. Select OK.

  9. Select Re-index project, and then select Start project re-index to save the changes.

  10. Select Refresh, and then select Acknowledge to complete the process.

JCMA 130

ERROR <project key> project-export: The filter ‘<filter name>’ has no owner assigned or no longer exists.

Refer the Filters owned by deleted users section in the KB article to resolve the error:

How to migrate all boards and filters with the Jira Cloud Migration Assistant

Apps checks

The Cloud Migration Assistant lists errors and warnings when it checks apps for any issues that can potentially impact the migration of your apps. Learn more about pre-migration checks for apps

Learn more about pre-migration checks for apps

We also provide App vendor checks, which are checks that app vendors (Marketplace Partners) run on your instance to highlight and provide resolutions steps for issues that may impact the migration of their app’s data to cloud.

Learn more about app-vendor checks

Pre-migration report

Pre-migration report is a ZIP archive that includes details of your migration, including migrated items, things that require attention, and summaries of users, groups, and configuration items. You can use it to verify what is being migrated and to find potential problems before you start.

To download the pre-migration report:

  1. Open your migration plan.

  2. Progress to the Review your migration screen.

  3. Select the Logs and reports tab.

  4. Download the pre-migration report.

The report contains many entries, out of which the problem summary, description, and solution are also included in the following table:

Problem summary

Problem Description

Solution

Unsupported custom field configuration

Migration of <custom_field_type_name> custom field type isn't supported. Therefore, the configuration for this field won't be migrated, and any items that reference it, such as workflow schemes and filters, may no longer work.

If you need this custom field, recreate it in your cloud site and use a CSV import to update the issues post-migration. Refer to the Adding additional entities with CSV section in this document:

What gets migrated with the Jira Cloud Migration Assistant

Unsupported custom field configuration

Migration of the <custom_field_name> custom field isn't supported. The value for this issue will not be migrated.

If you need this field value, use a CSV import to update the issues post-migration. Refer to the Adding additional entities with CSV section in this document:

What gets migrated with the Jira Cloud Migration Assistant

Unsupported issue type

During the migration, the <issue_type_name_A> issue type will be renamed to <issue_type_name_B> issue type.

Review the issue type after migration to ensure it functions as expected. Some JQL references may be affected and need to be updated after migration.

Unsupported notification scheme

The notification schemes aren't supported and won't be migrated.

The default notification scheme will be assigned to each project in the cloud site. Review the permissions post migration.

Missing configurations or references in the condition of the workflow

The workflow will be migrated. However, the condition on <transition_name> transition of the workflow will be skipped, which may impact the permissions in your cloud site.

Review the workflow post-migration to ensure that the permissions are set correctly. To identify workflows that might be affected during pre-migration, run SQL queries from this page:

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

Missing configurations or references in the transition of the workflow

 

The <transition_validator_name> validator isn't supported. The workflow will still be migrated. However, the validator on <transition_name> transition of the workflow will be skipped, which may impact the permissions in your cloud site.

Review the workflow post-migration to ensure that the permissions are correctly set. To identify workflows that might be affected during pre-migration, run SQL queries from this page:

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

Missing configurations or references in the post function of the workflow

The <name> post function isn't supported. The workflow will still be migrated, however the post function on <name> transition will be skipped, which may impact the workflow in your cloud site.

Review the workflow post-migration to ensure it functions as expected. To identify workflows that might be affected during pre-migration, run SQL queries from this page:

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

Unsupported custom event type

The notification for the event type <event_type_name> isn't supported through migration (custom event issue). The value for this issue will not be migrated.

If you need this field value, use a CSV import to update the issues post-migration.

Null filename for attachments

Attachments with a null value for the filename aren't supported and won't be migrated.

If you need this attachment on your cloud site, you need to first assign a non-null filename to the given attachment ID on your server and then run the migration.

Unsupported gadget

This gadget isn't supported and won't be migrated.

  1. In the server, from the Dashboards menu, select the dashboard identified in the Entity IDs or keys column of the CSV file.

  2. From the unsupported gadget identified in the Entity name column, select … > Delete.

  3. In the cloud site, open the migrated dashboard and select Edit.

  4. Identify the desired gadget from the Add a Gadget list and select Add.

  5. Select Done once you've added the gadget.

View the list of supported gadgets

Partially migrated gadget

Found errors while migrating this gadget; therefore, it will be migrated without its configurations. For error details, refer to the log files generated when creating the support zip.

Steps to create a support zip

  1. Identify the affected gadget and the corresponding dashboard from the log file.

  2. Open this dashboard on your cloud site.

  3. Select Edit.

  4. Select … > Configure in the affected gadget.

  5. Update the configuration value in this gadget.

  6. Select Save.

After you run the migration

If your migration fails or is incomplete, you can check the following items:

  • Error log

  • App migration progress logs

  • Post-migration report

Error log

To download the error log:

  1. Open your migration plan.

  2. Progress to the Review your migration screen.

  3. Select the Logs and reports tab.

  4. Download the error log.

Generic errors

Here’s a list of generic errors shown in the error log:

Error

Fixes / KB articles

 ERROR <Project_Key> project-import
We couldn't import Project Component <Project_Component_Name>.
Reason: name: A component with the name <Project_Component_Name> already exists in this project...
This caused <Number_of_Items> other items to fail.

We couldn't import Project Component - JCMA Error

ERROR <Project_Key> project-import We couldn't import Project Version <Version_Name> because of <Number_of_Occurrences> missing dependencies: Project <Project_Key>.
This caused <Number_of_Issues> other items to fail. Check the reasons for the missing dependencies on your server site.

We couldn't import Project Version because of missing dependencies: Project - JCMA Error

 <Project Key> project-import
We couldn't import Issue <Project Key>-<Issue Number> because of 1 missing dependencies:
Custom Field 'Sprint'. This caused <Number of Ocurrences> other items to fail.
Check the reasons for the missing dependencies on your server site.

We couldn't import Issue because of 1 missing dependencies: Custom Field 'Sprint'

 com.atlassian.jira.migration.orchestratorclient.OrchestratorClientErrorException: request to Migration Orchestrator failed
com.atlassian.jira.migration.orchestratorclient.OrchestratorServerErrorException: failed to send a request to server

Request to server or Migration Orchestrator failed in JCMA

 ERROR <Project_Key> project-export
The workflow: [Workflow_Name] transition [Transition_Name] Missing config [Config_Name] value refence [Value_Reference_Name] in workflow rule condition/validator or post-function [Workflow_Rule_Name].
Double-check the workflow rule for missing config values or references.

Workflow missing config values or references - JCMA Error

ERROR <project-key> project-import We couldn't import Comment <comment-id> (on Issue <issue-key> by '<user>' on <timestamp>). Reason: CommentBodyCharacterLimitExceededException: No message.

ERROR <project-key> project-import We couldn't import Issue <issue-key>. Reason: description: The entered text is too long. It exceeds the allowed limit of 32,767 characters..

"CommentBodyCharacterLimitExceededException: No message" or "The entered text is too long. It exceeds the allowed limit of 32,767 characters.." error message in JCMA

 ERROR <Project_Key> project-import
We couldn’t import Issue <Issue_Key> because of 1 missing dependencies: Project <Project_Dependency_Key>.
This caused <Number_of_Items> other items to fail.
Check the reasons for the missing dependencies on your server site.

We couldn't import Issue because of missing dependencies: Project - JCMA Error

ERROR <Project_Key> project-export
The workflow: [Workflow_Name] transition: [Transition_Name]
has unsupported custom field reference in config hidFieldsList
for workflow rule validator [Validator_Name].
Double-check the workflow rule for missing config values or references.

Workflow rules migrated via Jira Cloud Migration Assistant

ERROR <Project_Key> project-export
We couldn't export Issue <Issue_ID>.
Reason:
com.atlassian.greenhopper.manager.lexorank.LexoRankIntegrityException:
Expected exactly <X> rows; the maximum marker row and the lowest
ranked row for rank field[id=<Field_ID>].

List of all known Agile Lexorank error

Jira server throws LexoRankIntegrityException error during reindexing or reranking operations

sun.security.validator.ValidatorException:
PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

Unable to connect to SSL services due to "PKIX Path Building Failed" error

java.net.UnknownHostException: <AMAZON_S3_URL>
java.net.ConnectException: Connection refused (Connection refused)

Preparing your firewall to migrate using the Jira Cloud Migration Assistant

We couldn't import Issue ABCD-12345. Reason: DataAccessException: java.sql.SQLException: PSQL_TOO_MANY_CONNECTIONS Exception already occurred in this workcontext, skipping next getConnection. This caused X other items to fail

'FATAL too many connections' error when using PostgreSQL database due to user-specific connection limit

java.lang.OutOfMemoryError: Java heap space

Jira server crashes with OutofMemory Java heap space error

Errors specific to Jira Service Management

Here are errors specific to Jira Service Management.

Error

Fixes / KB articles

ERROR <Project_Key> project-export
We couldn't export Issue <Issue_ID>.
Reason: com.querydsl.core.QueryException:
Caught SQLServerException for <SQL_QUERY>

How to fix the collation of Microsoft SQL Server database for Jira manually | Jira | Atlassian Documentation

 

App migration progress logs

This section provides details about warning messages in app migration progress logs and suggestions on how to resolve them.

If you encounter multiple warning messages in your app log file, or if your app migration seems stuck:

  • contact the Marketplace Partner and provide them with the log files and your cloud site URL.

  • contact Atlassian support if the Marketplace Partner requires Atlassian help to resolve the warnings.

Warning message

Details

Fixes

Exception occurred in the server app

An error has most likely occurred in the server app. This may stop further migration operations in the server app, and could cause a timed-out app migration.

If the app’s migration does not settle, contact the Marketplace Partner and provide the following information:

The Marketplace Partner may direct you to contact Atlassian Support if they need Atlassian to help with server exception.

Failed to notify Cloud app about start of app migration

An failure error occurred when attempting to notify with the Cloud app that app migration has started. Multiple retries to notify the cloud app has not returned as successful response.

Notifying the cloud app is needed to allow Marketplace Partners to begin app migration. Potentially, this error can lead to a timed-out app migration.

If the cloud app does not get updated, contact the Marketplace Partner and provide the following information:

Post-migration report

Post-migration report is a ZIP archive that includes details of your migration, including migrated and not migrated items, and things that require attention. You can also compare it with the pre-migration report to verify that all important items have been migrated.

To download the post-migration report:

  1. Open your migration plan.

  2. Go to the Review your migration screen.

  3. Select the Logs and reports tab.

  4. Download the post-migration report.

This report contains many entries, out of which the problem summary, description, and solution is same as described in the pre-migration report.

How to contact Atlassian support

If you’re unable to fix the problem using this page, contact support.

For a quicker response from the support team, it’s recommended that you share a support zip with the Atlassian Support team. Learn how to create a Support ZIP

More information and support

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

Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.

Still need help?

The Atlassian Community is here for you.