/dms-schema-conversion

DMS Schema Conversion: Troubleshooting

Table of Contents

• Sync Exceptions
• Async Exceptions
• Outdated AWS CLI Version
• Verify Connectivity
• DDL Processing Statistics (Offline Source)

Sync Exceptions

These errors are returned immediately by the API call itself (start-*, create-*, describe-*). Surface the error to the customer and apply the fix before retrying.

Async Exceptions

These errors do not fail the initial API call. The operation starts successfully but later transitions to a failed status, visible when checking the corresponding describe-* command (see schema-conversion-operations.md for the full list).

Step 1 — Retrieve the error message

Use the corresponding describe-* command for the operation that failed (e.g., describe-metadata-model-imports, describe-metadata-model-conversions, describe-metadata-model-assessments, describe-metadata-model-creations, describe-metadata-model-exports-as-script). Extract ErrorDetails.defaultErrorDetails.message and match it to a group below.

Group 1 — Database Credentials

Messages:

• The credentials in the secret SOURCE are not valid. Check your username and password and try again.
• The credentials in the secret TARGET are not valid. Check your username and password and try again.
• The credentials in the secret are not valid. Check your username and password and try again.

Fix:

1. Inform the customer:

   "The credentials stored in your Secrets Manager secret are not valid. Please verify the username and password for your source/target database and update the secret value if needed."

2. Show the customer the secret name to check (retrieve from the migration project, do NOT display the secret value):

   aws dms describe-migration-projects \
     --filters Name=migration-project-identifier,Values=<migration_project_identifier>

3. Once the customer confirms the secret has been updated, proceed to Step 2.

Group 2 — Database Connectivity

Messages:

• Could not connect to the source database. Please verify your network configuration, server name, and port, then try again.
• Could not connect to the target database. Please verify your network configuration, server name, and port, then try again.
• Could not connect to the database. Please verify your network configuration, server name, and port, then try again.
• The DB connection has not been established. For details, see the log.

Fix:

1. Verify the server name and port in the data provider:

   aws dms describe-data-providers \
     --filters Name=data-provider-identifier,Values=<project_name>-source

2. Check security group egress rules — see Verify Connectivity.

3. Confirm the database is running and reachable from the configured subnets.

Group 3 — Database Not Found

Messages:

• The specified source database name was not found. Check your database name and try again.
• The specified target database name was not found. Check your database name and try again.

Fix:

1. Retrieve the database name currently configured in the data provider and show it to the customer:

   aws dms describe-data-providers \
     --filters Name=data-provider-identifier,Values=<project_name>-source

   Extract and display the DatabaseName from the settings so the customer can see what name DMS is using.

2. Ask the customer to confirm whether this database name exists on the server.

3. If the name is wrong, update the data provider:

   aws dms modify-data-provider \
     --data-provider-identifier <arn> \
     --engine <engine> \
     --settings '{...corrected settings...}'

Group 4 — S3 Access and Configuration

Messages:

• Access to the project storage is denied. Check you bucket, S3 role and try again.
• Access to project storage denied. Check your S3 bucket, role, region, and try again.
• Unable to access to S3. Check the name of your S3 bucket, the IAM role to access your bucket, and the Region, then try again.
• S3 settings are not valid. Check the name of your S3 bucket, the IAM role to access your bucket, and the Region, then try again.
• The export metadata error happened during publishing to S3. Check your bucket, S3 role and restart operation.
• The read metadata error happened during reading from S3.
• S3 bucket url with the selected project was not found. Please close and open your project again.

Fix:

1. Retrieve the S3 bucket path and S3 role ARN from the migration project and display them to the customer:

   aws dms describe-migration-projects \
     --filters Name=migration-project-identifier,Values=<migration_project_identifier>

   Extract and show SchemaConversionApplicationAttributes.S3BucketPath and SchemaConversionApplicationAttributes.S3BucketRoleArn.

2. Validate the bucket exists:

   aws s3api head-bucket --bucket <bucket_name>

3. Verify the S3 role trust policy includes dms.<region>.amazonaws.com:

   aws iam get-role --role-name <s3_role_name>

4. Verify the S3 role has the required permissions (s3:PutObject, s3:GetObject, s3:GetObjectVersion, s3:GetBucketVersioning, s3:GetBucketLocation, s3:ListBucket) on the bucket:

   aws iam list-attached-role-policies --role-name <s3_role_name>

5. Check the bucket policy does not explicitly deny DMS access:

   aws s3api get-bucket-policy --bucket <bucket_name>

Group 5 — S3 Versioning

Message:

• S3 bucket versioning is disabled. Please turn it on and try again.

Fix:

1. Retrieve the S3 bucket name from the migration project:

   aws dms describe-migration-projects \
     --filters Name=migration-project-identifier,Values=<migration_project_identifier>

   Extract SchemaConversionApplicationAttributes.S3BucketPath and display it to the customer.

2. Enable versioning on the bucket:

   aws s3api put-bucket-versioning \
     --bucket <bucket_name> \
     --versioning-configuration Status=Enabled

Group 6 — Secrets Manager Access

Messages:

• The Secret does not exist. Please check the Secret name, IAM secret role, and region.
• DMS Schema Conversion is unable to process the request at this time because data from Secrets Manager is not available. Please check your network configuration and try again.
• Unable to access AWS Secrets Manager: <details>

Fix:

1. Retrieve the secret ARNs and secrets role ARN from the migration project and display them to the customer:

   aws dms describe-migration-projects \
     --filters Name=migration-project-identifier,Values=<migration_project_identifier>

   Extract and show SecretsManagerSecretId from both source and target data provider descriptors, and SecretsManagerAccessRoleArn.

2. Verify each secret exists:

   aws secretsmanager describe-secret --secret-id <secret_arn>

3. Verify the secrets role trust policy includes dms.<region>.amazonaws.com:

   aws iam get-role --role-name <secrets_role_name>

4. Verify the secrets role has secretsmanager:GetSecretValue and secretsmanager:DescribeSecret on the secret ARNs:

   aws iam list-attached-role-policies --role-name <secrets_role_name>

5. If the message mentions network unavailability, check that the DMS subnets have outbound access to Secrets Manager (via NAT gateway or VPC endpoint).

Group 7 — SSL / Certificate

Message:

• Verify that your database has SSL configured and doesn't provide self-signed certificates (certificates that were signed by an unknown Certificate Authority). By default, SSL isn't configured in your database.

Fix:

1. If SSL is not required, update the data provider to set SslMode: none.
2. If SSL is required, ensure the database uses a certificate signed by a trusted CA.
3. Update the data provider settings accordingly.

Group 8 — Insufficient Database Privileges

Message:

• The specified account does not have sufficient privileges for working with one or several objects.

Fix:

1. The database user does not have enough permissions to perform the requested operation.
2. Guide the customer to set up the correct database credentials based on:
   • For source databases: source data provider prerequisites
   • For target databases: target data provider prerequisites
3. Update the secret if the user needs to be changed.

Group 9 — Project / Configuration Issues

Messages:

• DMS Schema Conversion cannot open the project because it is already opened.
• The wrong project was selected for opening. Please verify the project identifier and try again.
• The Schema Conversion Application Attributes were not provided. Please add the required data to the Migration Project and try again.
• The project settings format is not valid. Please modify the field value and try again.
• DMS Schema Conversion cannot create the project because it already exists.
• DMS Schema Conversion cannot process your request because the Conversion does not exist.

Fix:

1. Verify the migration project identifier is correct:

   aws dms describe-migration-projects \
     --filters Name=migration-project-identifier,Values=<migration_project_identifier>

2. Check that SchemaConversionApplicationAttributes (S3 bucket path and S3 role ARN) are set on the project.

3. If the project configuration is incomplete or corrupted, recreate it via the setup wizard with the same or a new project name.

Group 10 — Capacity / Transient Errors

Messages:

• Capacity is unavailable at this time. Please try again later.
• DMS Schema Conversion cannot process your request. Please try again later or contact the support team.
• The service is currently experiencing high load. Please try your request again later.

Fix: These are transient errors. Wait 5 minutes and retry the operation.

Step 2 — Retry

After the customer confirms the fix, ask:

"Would you like to retry the operation? (yes / no)"

If yes, return to the appropriate action. If no, return to the Actions Menu.

Group 8 — Offline Source Import Failure (Unexpected application error)

Messages:

• Unexpected application error.

Context: This generic error occurs specifically during start-metadata-model-import for offline source data providers. The most common cause is a DatabaseName mismatch between the data provider settings and the DDL script content.

Fix:

1. Retrieve the data provider settings and extract the configured DatabaseName:

   aws dms describe-data-providers \
     --filters Name=data-provider-identifier,Values=<project_name>-source

   Show the customer the DatabaseName value from Settings.MicrosoftSqlServerSettings.DatabaseName.

2. Download one DDL script from S3 and check the actual database name:

   aws s3 cp <S3Path><first_file.sql> - | head -5

   Look for USE [<name>] or CREATE DATABASE [<name>]. Do not log or persist this output — DDL content may contain sensitive schema information. Use it only transiently to extract the database name.

3. If the configured DatabaseName does not match the database name in the DDL scripts, modify the data provider with the corrected DatabaseName. Keep all other settings (ServerName, Port, SslMode, S3Path, S3AccessRoleArn) unchanged from the describe output.

4. If DatabaseName was already correct, check DDL processing statistics in the S3 artifacts bucket:

   aws s3 cp s3://<artifacts_bucket>/<project_name>-migration-project/ddl-statistics/ds.csv -

   Look for files with FAILED status in the CSV — these indicate individual DDL parsing errors.

5. Retry the import after the fix.

Outdated AWS CLI Version

If a DMS command fails with Invalid choice or argument operation: Invalid choice, the installed AWS CLI version does not support the operation.

Fix:

1. Check the current version:

   aws --version

2. Update to the latest version following the AWS CLI installation guide.

3. Verify the operation is now available:

   aws dms <operation> help

Verify Connectivity

If the error indicates a network or connectivity issue, read DMS SC network configuration and guide the customer through setting up the correct network configuration.

DDL Processing Statistics (Offline Source)

For offline source projects, DMS produces processing statistics in the project's S3 bucket after import, conversion, or assessment operations. Check these statistics proactively when results contain fewer objects than expected or when an operation completes without errors but the metadata tree appears incomplete.

Retrieve the statistics:

aws s3 cp s3://<project-bucket>/<migration-project-folder>/ddl-statistics/ds.csv ./ds.csv

Review the output for entries indicating processing failures. Common causes: malformed DDL, unsupported statements (DML/DROP), encoding issues, or non-compliant file structure. Refer to Phase 3d of the setup wizard for DDL structure requirements.