--- title: "Troubleshooting Xray Migration" canonical: "https://docs.getxray.app/space/XRAY/1154711555/Troubleshooting%20Xray%20Migration" format: markdown --- > Macro (rw-ui-expands-macro) > > > Macro (rw-expand) > > > Macro (toc) # Introduction This document is intended to troubleshoot Xray migrations from Jira Server/Data Center to Cloud. It provides guidance on common issues, diagnostics, and recommended solutions to ensure a smooth migration. We are continuously working to improve and reduce the effort required to migrate Xray to the Cloud. Nevertheless, we recognize that issues may affect your migration and cause a failure.  Our Migration Effort Score is rated by our customers as "Normal," and a big percentage of customers do not face any blockers. The success depends on understanding and following all the necessary steps, as well as on the data size and complexity. > ⚠️ This guide does not cover the Xray migration process/best practices, how to use the [Jira Cloud Migration Assistant (JCMA)](https://support.atlassian.com/migration/docs/jira-cloud-migration-assistant/) to perform the Xray migration, or how to plan the Xray migration. Those topics are covered in the dedicated Xray documentation. > ⚠️ > ⚠️ Before starting any Test migration, please [contact the Xray Cloud Migration Support team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) and inform them about your migration plans. We will provide guidance, share all necessary steps, and support you throughout your migration to the Cloud. > ⚠️ > ⚠️ Please avoid creating multiple tickets for the same migration. **Keep all migration-related discussions in a single ticket **to prevent miscommunication, keep the conversation organized, and ensure all relevant information is available if escalation is required. > Macro (panel) > > For detailed information about how to plan the Xray migration and the process that needs to be followed, please refer to the dedicated documentation: > > 1. [Xray Pre-Migration Best Practices](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154613253). This documentation provides a comprehensive, step-by-step guide for migrating Xray Data Center data to Xray Cloud. > 2. [How to plan the Xray Migration to the Cloud](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1152811013). This documentation is designed to guide you through the entire migration process, helping with planning, running Test migrations, and executing the production migration. > 3. [How to use the JCMA to migrate Xray properly.](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/1154351109) This guide shows how to use the JCMA to migrate Xray from Jira Server/Data Center to Cloud, focusing on strategy selection, Xray installations, prerequisites, and migration monitoring. # Operations ## If Your Test Migration Fails [Inform the Xray Migration team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) so that the team can investigate and find the cause of the errors. When reaching out to the Xray Cloud Migration for assistance, please include: - Migration plan name. - Cloud URL. - Jira Support ZIP file. ## Xray Preload Attachment Statuses During the attachment preload process, Xray looks for each attachment listed in the *AO_8B1069_ATTACHMENT* table and attempts to locate the corresponding files in the local filesystem. It then exports the available files and sends them to JCMA. When files are missing from the disk, Xray logs a warning and reports this to JCMA, which then sets the preload status for each project as follows: - **Failed Status: **JCMA marks the preload as failed only when no attachments for a given Project (or Projects) can be found. In this case, the preload status is failed. - **Incomplete Status: **if some attachments are found and exported, but others are missing, JCMA marks the preload as incomplete, and all available files are successfully migrated. - **Success Status: **this status means all Project(s) attachments were found on disk and successfully migrated to the Cloud. > ⚠️ A status of **Failed **does not indicate a failure in the preload process itself. It simply means the required files were not present on disk and therefore could not be exported. ### Handling Missing Attachments During Xray Preload Xray logs a warning when files are missing and reports this to JCMA. However, this will **not cause the migration to fail**. Instead, the migration will be marked as **incomplete** because some attachments could not be migrated. If a new preload is performed for the same project, the same warning will appear unless the missing files are restored on disk. In most migrations, missing attachment files are expected. Therefore, missing attachments **should not cause the preload process to fail**. This behavior has been consistently observed in JCMA since Xray implemented support for attachment preloading. ### How the Xray Preload Attachments Work Xray Data Center receives a trigger to start uploading the attachments. When the export is completed, JCMA sends a trigger to Xray Cloud, which copies all these files and stores them in Xray’s S3 in a special folder, waiting to start the actual migration so it can then use the attachments and place them in the correct entities. ### Most Common Reasons for Migration Failures: Solutions | **Problem** | **Diagnosis** | **Solution** | **KB article reference** | | --- | --- | --- | --- | | Data was modified during the migration process; the Jira Project did not migrate at 100%, new issues being created, edited, updated. | Check internally with the teams that work with the Projects being migrated to ensure no new data is created, and no existing data is changed | There are two options:
**Option 1: **
1. Delete the already-migrated Projects in the Cloud. 2. Create a new migration plan with Xray, and add the projects to the migration.
**Option 2: **
1. **You will need to delete the Jira Cloud projects whose data was modified during the migrations.** This action needs to be performed on the Jira Cloud. 2. Once those projects have been deleted in Jira Cloud, **create a new configuration plan that includes only the failed projects (excluding Xray), then migrate them again**. 3. If those Projects migrate successfully, access the **migration from the original plan,** then re-run the Xray migration using the Re-run feature in JCMA on the original plan; it should indeed work.
> ⚠️ The second option does not work in all cases, so we need to review each case individually. Please [contact the Xray Support team](https://jira.getxray.app/servicedesk/customer/portal/2) for guidance. | N/A | | The Xray Data Center version is not compatible with Jira Cloud Migration Assistant | N/A | Upgrade Xray version to the latest version that your Jira Data Center Support | - [[Xray] Do I need to upgrade Xray to migrate to the Cloud? Which version do I need to upgrade?](https://docs.getxray.app/space/ProductKB/46268631) - [[Xray] Server/DC to Cloud Migrations (JCMA) – Advantages of Updating the Xray App Prior to Migration](https://docs.getxray.app/space/ProductKB/46269308) | | Test Issue Linkage/ missing Issues | > ℹ️ This does not cause the Xray migration to fail. But on the Xray Cloud, the Test Coverage will be missing/broken.
In Jira Cloud, *go to Jira Settings → Work Items → Work item features → Work Item Linking *and check the link Name: Test with the Outward and Inward Description: tests/is tested by.
Then, go to Jira Data Center, go to *Jira Administration → Issues → Issue Features → Issue Linking, *and* *you'll see a link Name: Tests with the *Outward* and *Inward Description*: tests/tested by.
This should have been changed to match its counterpart in the Jira Cloud. Both the *Name* and the *Outward* and *Inward Description*. | > ℹ️ This does not cause the Xray migration to fail. But on the Xray Cloud, the Test Coverage will be missing/broken.
- Compare both instances of the issue linking for the Test: compared both instances of Jira Cloud and Server/DC - In the Server/DC instance, you can check the Issue Links on the following path: *Configuration* > *Issues* > *Issue linking*: - On the Cloud instance, you can check the Issue Links on the following path: *Work Items > Work Item linking:* - Take screenshots from the Jira Data Center and the Cloud, and [contact the Xray Support team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) for guidance.
The process will be to:
- Perform a quick Test on the Xray Cloud, create a new Project/Space, and add Xray to this Project. On the Test Coverage, add the Issue type Story. - Create an Issue for the Story, and add some tests to it. Check which Issue Xray is looking for. - Then, access the *Work Items >Work Item linking*, delete the issue linking migrated from the Data Center, and migrate all the issues to the correct issue linking.
> ⚠️ Please do not perform the process if you have any doubts; contact the Xray Support team. | N/A | | Migration failed due to archived Projects | In Jira Data Center, go to *Jira Administration → Projects → Archived Projects*, and check if any of the Projects included in the migration are present here | There are two options:
**Option 1: **
You can go to Jira Cloud, unarchive the migrated Archived Projects, and **re-run** the migration.
**Option 2: **
1. Unarchive the Projects on the Jira Data Center. 2. Delete the already migrated Projects on the Cloud. 3. Create a new migration plan, add the projects to the migration, including the ones that were unarchived, and add the Xray to the migration plan.
> ℹ️ The Xray Re-run option will work for this case | [[Xray] Server/DC to Cloud Migrations (JCMA) – Xray migration got failed due to archived projects](https://docs.getxray.app/space/ProductKB/140804240) | | Migration failed due to Issue Security Schemes | In Jira Data Center, go to *Jira Administration → Issues → Issue Security Schemes* and check if there are any for the Projects included in the migration, and if they have the *Any logged-in user* permission | There are two options:
**Option 1:**
You can resolve the issue by adding "Any logged-in user" to the Issue Security Schemes directly on the Cloud site and then re-running the app migration from JCMA.
> ⚠️ For future migrations, the permission should be added on the Data Center side before running the Jira migration to prevent this issue from recurring
**Option 2:**
- Remove Issue security schemes from projects before migrating, or set Issue security to *Any logged-in user*. - Create a new migration plan, and add the projects you have migrated** **(it's important that Xray is not included in this plan; the project should be migrated only with Jira). - Access the failed migration plan, then re-run the Xray migration using the Re-run feature in JCMA on the original plan; it should indeed work.
> ℹ️ The Xray Re-run option will work for this case | ⁠⁠[[Xray] Server/DC to Cloud Migrations (JCMA) – Xray migration failed due to issues with Security Schemes](https://docs.getxray.app/space/ProductKB/140574916) | | Migration failed due to missing Projects | In Jira Data Center, go to *Jira Administration → Manage Apps → Xray → Cloud Migration. *Click *Download project dependency map,* then use the **Cloud Migration Pre-Flight Checker.** The Project Dependency Map will create a file where you´ll be able to check, by Group, which Projects have Xray dependencies. Using the Cloud Migration Pre Flight Checker, you can verify the dependencies between them.
You'll need to check the Projects included in the migration and whether the others in each corresponding Group were migrated together. | 1. Check the Xray Dependency Map. Go to *Jira Administration → Manage Apps → Xray → Cloud Migration. *Click *Download project dependency map,* then use the **Cloud Migration Pre Flight Checker.** 2. Delete the already migrated Projects on the Cloud. 3. Create a new migration plan, add the projects to it, including those that were missing, and add Xray to the plan.
> ⚠️ The Xray Re-run option will not work for this case | [[Xray] Can I migrate only certain projects from Server/DC to Xray Cloud?](https://docs.getxray.app/space/ProductKB/46268619) | | Migration failed due to mismatched Xray Issue types | Check the list of Xray Issue types in both Jira Data Center and Jira Cloud, ensuring that Test, Test Execution, Test Set, Test Plan, Precondition, and Sub-Test Execution are present and named consistently. | 1. The best option is to delete all migrated projects in Jira Cloud. 2. Rename the Xray Issue types to match in both instances. Once this is done. 3. On the Jira Data Center, create a new migration plan, add the Projects, and run the migration.
> ⚠️ There’s another process: c[ontact the Xray Support team](https://jira.getxray.app/servicedesk/customer/portal/2/create/37) so we can remap the Xray Cloud to look for the Issue types migrated from the Data Center. Then you can rerun the migration for Xray without creating a new plan or performing the Jira migration. > ⚠️ > ⚠️ However, this does not work in all cases, so we need to review each case on a case-by-case basis. | [[Xray] Migration from Server/DC to the Cloud Xray issues types MUST be equal in both instances](https://docs.getxray.app/space/ProductKB/141885510) | | Xray Sub Test Execution is not installed on Xray Cloud | In Jira Cloud, go to *Jira Settings → Marketplace Apps → Xray → Health Check *and check if Xray Issue Type Sub Test Execution is installed | 1. Go to *Jira Settings → Work Items → Work types → Sub-Task* and ensure Jira Sub-tasks are enabled, then reinstall Xray using the Health Check in Jira Cloud. 2. For this, the best option is to delete all migrated projects in Jira Cloud. 3. On Jira Data Center, create a new migration plan, add the projects, and run the migration.
> ⚠️ The Xray Re-run option will not work for this case | [Xray Cloud Health Check shows that the Xray Sub Test Execution issue type is not installed](https://docs.getxray.app/space/ProductKB/141590534) | | Add-ons blocking or failing the migration | In the Jira Data Center, go to *Jira Administration → Manage Apps* and check if the Checklist or Jira Misc Custom Fields (JMCF) apps are present | > ⚠️ Pause or disable these add-ons until the Xray migration completes, then re-enable them | [[Xray] Add-ons that are currently incompatible with Xray data migration](https://docs.getxray.app/space/ProductKB/192380971) | | Xray appears as *Skipped* in JCMA due to incorrect Cloud Migration target configuration | | Go to *Jira Administration -> Manage Apps -> Xray -> Cloud Migration*, set the correct Cloud Migration target (Standard or Enterprise, according to your destination), click *Save*, and re-run the migration | [[Xray] Xray/Xray Enterprise Skipped in JCMA due to Incorrect Cloud Migration Target](https://docs.getxray.app/space/ProductKB/958038017/[Xray]+Xray%2FXray+Enterprise+Skipped+in+JCMA+due+to+Incorrect+Cloud+Migration+Target) | > Macro (rw-ui-expands-macro) > > > Macro (rw-expand) > > If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAY/pages/301501383).