Troubleshoot Astra DB Sideloader

Learn how to troubleshoot common Astra DB Sideloader issues.

Migration status is outdated

You can use the DevOps API to check the migration status at any time. However, it can take a few minutes for the DevOps API to reflect status changes during a migration. Immediately calling the DevOps API after starting a new phase of the migration might not return the actual current status.

Get new upload credentials

If your credentials expire, do the following:

Use the MigrationStatus endpoint to generate new credentials:
```
curl -X GET \
    -H "Authorization: Bearer ${token}" \
    https://api.astra.datastax.com/v2/databases/${dbID}/migrations/${migrationID} \
    | jq .
```
A successful response contains a MigrationStatus object. It can take a few minutes for the DevOps API to reflect status changes during a migration. Immediately calling this endpoint after starting a new phase of the migration might not return the actual current status.
Continue the migration with the fresh credentials.

If you set environment variables for your credentials, be sure to update those values.

Retry a failed migration

If a migration fails, there are two ways that you can reattempt the migration. The option you use depends on the type of error that occurred.

If you are able to resolve the cause of the failure without modifying the migration directory contents, you can relaunch the migration using the data already present in the migration directory. Otherwise, you must abandon the failed migration and restart the entire migration process from the beginning.

The two most common errors are as follows:

Schema discrepancies: There is a mismatch between the origin and target schemas. To resolve this error, you can align the schemas and relaunch the migration.
Invalid data in migration directory: The data uploaded to the migration directory is invalid or improperly formatted. Common causes include data corruption, incomplete upload due to a timeout, malformed file paths, and the presence of invalid data.

When this type of failure occurs, you must abandon the failed migration and restart the entire migration process. For more information, see Restart a failed migration.

Relaunch a failed migration

Check the migration status for an error message related to the failure:
```
curl -X GET \
    -H "Authorization: Bearer ${token}" \
    https://api.astra.datastax.com/v2/databases/${dbID}/migrations/${migrationID} \
    | jq .
```
A successful response contains a MigrationStatus object. It can take a few minutes for the DevOps API to reflect status changes during a migration. Immediately calling this endpoint after starting a new phase of the migration might not return the actual current status.
If possible, resolve the issue described in the error message.

For example, if there is a problem with the schema in the target database, make sure that your schemas align, as described in Configure the target database.
Repeat the launch command that you used to import the data, and continue the migration process from there.

If the migration fails again, see Restart a failed migration.

Restart a failed migration

When a migration fails due to a problem with the data uploaded to the migration directory, you must completely restart the migration.

This is because you cannot change the data in the migration directory after you upload it. For example, if your snapshots contain corrupt data, you have to restart the migration with new snapshots and a new migration directory.

Review the origin cluster requirements to ensure that your snapshot doesn’t contain invalid data, including materialized views and encrypted data.
If necessary, create new snapshots of any invalid snapshots.

If your snapshots don’t appear to contain invalid data, continue to the next step.
If necessary, reprepare the target database. There are two reasons you might need to do this:
- The origin and target schemas don’t match.
- The migration reached a point that some data was loaded to the target database. This is unlikely, but, if this happens, you must drop the table from your target database, and then recreate the table in the target database.
  
  In this case, if the migration didn’t fail due to a problem with the snapshot data, you can potentially reuse the existing snapshots for the new migration.
Repeat the remainder of the migration process from Initialize the migration.

This starts a fresh migration with a new migration directory, a migration ID, and upload credentials.
If the migration fails again and you are unable to determine the cause of the failure, contact DataStax Support.