Plan your Cloud migration
Documents to help you prepare to migrate your Atlassian Server products.
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
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 Server 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 Software 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 |
There are two things you can check before running the migration:
Pre-migration checks
Pre-migration report
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
Here’s a brief description of statuses shown by pre-migration checks.
Symbol | Description |
---|---|
The check has passed. You can proceed with your migration. | |
You can proceed with your migration, but you need to be aware of a potential issue. Expand the warning messages to view details. | |
You can’t proceed with your migration until you resolve the error. Expand the error messages to view details. | |
The check wasn’t completed due to an unexpected error. Refresh the checks or contact Atlassian support. |
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. |
We couldn’t check for users count limit | The Jira Cloud Migration Assistant authentication token might have expired. |
We couldn’t check for projects in your cloud site | The Jira Cloud Migration Assistant authentication token might have expired. |
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:
Reason 2: Your cloud site couldn’t be found or your Jira Cloud subscription has been deactivated due to inactivity.
|
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 | |
Invalid email addresses |
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:
|
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:
|
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:
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:
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. | |
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:
|
JCMA 701 | ERROR CROSS-PROJECT-DATA project-export Exception Message generated on executing query for fetching arPlanPermissions -> <exception message> | 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:
|
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 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:
Open your migration plan.
Progress to the Review your migration screen.
Select the Logs and reports tab.
Download the pre-migration report.
If your migration fails or is incomplete, you can check the following items:
Error log
App migration progress logs
Post-migration report
To download the error log:
Open your migration plan.
Progress to the Review your migration screen.
Select the Logs and reports tab.
Download the error log.
Here’s a list of generic errors shown in the error log:
Error | Fixes / KB articles |
---|---|
ERROR <Project_Key> project-import | |
ERROR <Project_Key> project-import We couldn't import Project Version <Version_Name> because of <Number_of_Occurrences> missing dependencies: Project <Project_Key>. | We couldn't import Project Version because of missing dependencies: Project - JCMA Error |
<Project Key> project-import | We couldn't import Issue because of 1 missing dependencies: Custom Field 'Sprint' |
com.atlassian.jira.migration.orchestratorclient.OrchestratorClientErrorException: request to Migration Orchestrator failed | |
ERROR <Project_Key> project-export | |
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.. | |
ERROR <Project_Key> project-import | We couldn't import Issue because of missing dependencies: Project - JCMA Error |
ERROR <Project_Key> project-export | |
ERROR <Project_Key> project-export | List of all known Agile Lexorank error Jira server throws LexoRankIntegrityException error during reindexing or reranking operations |
sun.security.validator.ValidatorException: | Unable to connect to SSL services due to "PKIX Path Building Failed" error |
java.net.UnknownHostException: <AMAZON_S3_URL> | 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 | |
java.lang.OutOfMemoryError: Java heap space |
Here are errors specific to Jira Service Management.
Error | Fixes / KB articles |
---|---|
ERROR <Project_Key> project-export |
|
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. | If the cloud app does not get updated, contact the Marketplace Partner and provide the following information:
|
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:
Open your migration plan.
Progress to the Review your migration screen.
Select the Logs and reports tab.
Download the post-migration report.
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
We have a number of channels available to help you with your migration.
For more migration planning information and FAQs, visit the Atlassian Cloud Migration Center.
Have a technical issue or need more support with strategy and best practices? Get in touch.
Looking for peer advice? Ask the Atlassian Community.
Want expert guidance? Work with an Atlassian Partner.
Support for Atlassian Server products ends in February, 2024. Learn more about the Server end of support timeline.
Was this helpful?