Migration troubleshooting

This page describes common migration status values and explains how to resolve errors when using the Migration Assistance API.

Migration statuses

During migration, two status indicators track progress:

• stagingStatus: Represents the status of data in the staging area. It indicates whether the data has been successfully uploaded and validated.
• importStatus: Represents the status of data during the import phase. It shows whether the data has been successfully moved from the staging area to the target environment.

The table below provides a description of each status:

Status	Staging status	Import status
Pending	Data has not yet been validated.	Data import has not yet started.
InProgress	Validation is currently running on the staged data.	The import process is currently running to move data into the target environment.
ValidationFailure	Validation failed due to missing fields, invalid formats, or rule violations. Retry or delete the failed items. See Staging issues.	-
TechnicalFailure	A system or processing error occurred during validation. Retry or delete the failed items. See Staging issues.	A system or processing error occurred during import. Contact your Customer Service representative for support.
Completed	All data has passed validation and is ready for import.	Data has been successfully imported into the target environment.

Migration activity

Each migration has an activity state that represents the overall lifecycle of the migration process. The activity state determines which operations are allowed.

Activity	Description
Active	The migration is in progress. You can load data, run validation, import, and count jobs.
Completed	The migration has been fully processed. No further modifications or jobs can be started. You can still start a count job and view the migration status and job results.
Cancelled	The migration was explicitly cancelled. No further modifications or jobs can be started. To start a new migration, create a new migration process.

Common issues

Staging issues

The staging phase is where you upload and validate your data before importing it into the target environment. The system checks your data and reports any issues.

If validation fails, the response includes details for each failed record, as shown in the following example:

{
  "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "jobType": "ValidateStaging",
  "isValid": false,
  "errors": [
    {
      "component": "Counterparties",
      "referenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "field": "addresses[0].countryCode",
      "message": "Invalid country code: 'XX' does not exist in configuration"
    },
    {
      "component": "Collaterals",
      "referenceId": "c3d4e5f6-a1b2-3456-789a-bcdef0123456",
      "field": "counterpartyReferenceIds[0]",
      "message": "Referenced counterparty does not exist in staging or live data"
    }
  ]
}

The error response includes the following fields:

• component: The component that failed validation.
• referenceId: The specific entity reference ID that caused the error.
• field: The exact field path where validation failed.
• message: The reason the validation failed.

Remedy

To resolve validation errors, follow these steps:

1. Identify the records that failed validation and fix the issues.

2. Upload the corrected records again to the staging area using the same migration reference ID. This will overwrite the failed records.

   Alternatively, use the delete functionality to remove the failed items from the staging area. Refer to Load data for instructions.

3. Re-run the validation job to verify the updated data. Once the status changes to Completed, the data is ready for import.

Import issues

The import phase transfers validated data from the staging area into the target environment.

Some records may fail during the import process, as shown in the example below:

{
  "referenceId": "b2c3d4e5-f6a1-2345-6789-abcdef012345",
  "jobType": "Import",
  "status": "Completed",
  "numberOfStagedEntities": 2500,
  "numberOfImportedEntities": 2450,
  "errors": [
    {
      "component": "Collaterals",
      "message": "IMPORT_FAILED: 50 entities failed due to external service timeout"
    }
  ]
}

The error response includes the following fields:

• component: The component that experienced import issues.
• message: The reason the import failed.

Due to the distributed nature of the import process, the system supports roll-forward error handling only. During a retry, the system processes only the records that failed to import previously. Records already imported and marked as IsImported remain unchanged.

For some complex errors, manual intervention may be necessary.

Counts job issues

Counts job cannot be started

A counts job can be started only after a successful import. If you receive an error when starting a counts job, check the following causes:

• Import not completed: The import status must be Completed before you can start a counts job. Verify the migration status using the Get migration status endpoint.
• Migration is canceled: A canceled migration does not allow any new jobs. You must start a new migration process.

Mismatched numbers

If the values of stagedRows and importedRows do not match, some entities may not have been imported correctly.

To resolve the issue:

1. Review the import job result to check for errors during the import. See Monitor job result and progress.
2. Stream the migration logs filtered by ERROR log level to identify specific failures. See Stream migration logs.

If the import job completed with partial failures, you can retry the import to process only the failed records. In case the issue persists, contact your Customer Service representative for support.