How do I troubleshoot AWS DMS endpoint connectivity failures?

Resolution

When you test the connection from your replication instance to the source or target endpoint, you might receive connectivity issues or native database issues.

If there's a connection issue between the replication instance and the source or target, then you receive errors similar to the following:

• "Application-Status: 1020912, Application-Message: Failed to connect Network error has occurred, Application-Detailed-Message: RetCode: SQL_ERROR SqlState: HYT00 NativeError: 0 Message: [unixODBC][Microsoft][ODBC Driver 13 for SQL Server]Login timeout expired ODBC general error."
• "Application-Status: 1020912, Application-Message: Cannot connect to ODBC provider Network error has occurred, Application-Detailed-Message: RetCode: SQL_ERROR SqlState: 08001 NativeError: 101 Message: [unixODBC]timeout expired ODBC general error."
• "Application-Status: 1020912, Application-Message: Cannot connect to ODBC provider ODBC general error., Application-Detailed-Message: RetCode: SQL_ERROR SqlState: HY000 NativeError: 2005 Message: [unixODBC][MySQL][ODBC 5.3(w) Driver]Unknown MySQL server host 'mysql1.xxxxx.us-east-1.rds.amazonaws.com' (22) ODBC general error."

If the failure occurs because of native database issues, such as database permission or authentication errors, then you receive an error similar to the following:

"Application-Status: 1020912, Application-Message: Cannot connect to ODBC provider Network error has occurred, Application-Detailed-Message: RetCode: SQL_ERROR SqlState: 08001 NativeError: 101 Message: [unixODBC]FATAL: password authentication failed for user "dmsuser" ODBC general error."

Note: It's a best practice to test the connection from the AWS DMS replication instance to the endpoints after you create your source and target endpoints. Complete the test before you start the AWS DMS migration task.

Resolve connectivity issues for resources that you host on AWS

Check whether you can establish a connection between the source or target database and the replication instance. Based on your use case and network infrastructure, connect your source or target database to a replication instance in a public subnet or private subnet. For more information, see Setting up a network for a replication instance.

Note: AWS DMS versions 3.4.7 and later require that you configure AWS DMS to use Amazon Virtual Private Cloud (Amazon VPC) endpoints. Or, you must use public routes to all your source and target endpoints that interact with certain AWS services.

Check your replication instance configuration

In your replication instance, confirm that your configuration includes the following rules:

• An Outbound Rule for the IP address with the port of the source or target database in the security group. By default, the Outbound Rule of a security group allows all traffic. Security groups are stateful, so you can keep the default Inbound Rule.
• An Outbound Rule for the IP address with the port of the source or target database in the network access control list (ACL). By default, the Outbound Rule of a network ACL allows all traffic.
• An Inbound Rule for the IP address with the ephemeral ports of the source or target database in the network ACL. By default, the Inbound Rule of a network ACL allows all traffic.

Check your source or target database configuration

In your source or target database, confirm that your configuration includes the following rules:

• An Inbound Rule for the IP address of the replication instance or the CIDR block of the subnet group of the replication instance. The Inbound Rule must include the port of the source or target database in the security group. Security groups are stateful, so you can keep the default Outbound Rule.
• An Inbound Rule for the IP address of the replication instance or the CIDR block of the subnet group of the replication instance. The Inbound Rule must include the port of the source or target database in the network ACL. Confirm that there's no explicit deny rule for the IP address and port.
• An Outbound Rule for the IP address or the CIDR block of the subnet group of the replication instance with ephemeral ports in the network ACL. By default, the Outbound Rule of a network ACL allows all traffic.

It's a best practice to configure your network to allow the CIDR block of the subnet group of the replication instance. The IP address of the replication instance changes during a failover or host replacement event.

Determine the IP addresses and CIDR block of a subnet group

To set up inbound and outbound rules, determine the IP addresses and CIDR block of the subnet group. You can use either the AWS DMS console or the AWS Command Line Interface (AWS CLI).

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

AWS DMS console

Complete the following steps:

1. Open the AWS DMS console.
2. In the navigation pane, choose Replication instances.
3. Select your replication instance.
4. Under Details, copy the Public IP address, Private IP address, and the Replication subnet group of your replication instance.
5. Under Replication subnet group, choose the link to access the subnet group page. Copy the name of each subnet in the subnet group.
6. To verify the CIDR block of each subnet, open the Amazon VPC console.
7. In the Subnets tab, search for the subnets. For each subnet, note the CIDR block.

AWS CLI

To determine the CIDR block for each subnet, run the describe-subnets AWS CLI command:

aws ec2 describe-subnets --filters Name=subnet-id,Values="$(aws dms describe-replication-instances --filters "Name=replication-instance-id,Values=replication-instance-name" --query "ReplicationInstances[*].ReplicationSubnetGroup.Subnets[*].SubnetIdentifier" --output text | sed -e 's/\t/,/g')" --query "Subnets[*].{SubnetId:SubnetId,CidrBlock:CidrBlock}" --output table

Note: Replace replication-instance-name with the name of your replication instance.

To determine the IP addresses of the replication instance, run the describe-replication-instances command:

aws dms describe-replication-instances --filters "Name=replication-instance-id,Values=replication-instance-name" --query "ReplicationInstances[*].{ReplicationInstancePublicIpAddresses:ReplicationInstancePublicIpAddresses,ReplicationInstancePrivateIpAddresses:ReplicationInstancePrivateIpAddresses}" --output table

Note: Replace replication-instance-name with the name of your replication instance.

Resolve connectivity issues for on-premises resources

If you host your source or target database on-premises, then confirm that the database allows incoming connections from the AWS DMS replication instance. To confirm, check with your network administrator. Also, check that a firewall doesn't block communication to the source or target database.

Make sure that you correctly set up the DNS configuration. If you require DNS resolution, then use the Amazon Route 53 Resolver. For information about how to use an on-premises name server to resolve endpoints with the Route 53 Resolver, see Using your own on-premises name server. Or, create a new AWS DMS instance through the AWS CLI to use a customer DNS name server (--dns-name-servers) to resolve DNS issues. By default, AWS DMS instances use DNS names that Amazon provides for resolutions. For more information, see create-replication-instance.

Note: When you configure the source or target to use custom DNS, AWS DMS endpoints might fail.

Check that your Amazon Elastic Compute Cloud (Amazon EC2) instance has the same network configurations as the AWS DMS replication instance with the connectivity issues. To troubleshoot network connectivity, first run the following command on the new Amazon EC2 instance:

telnet database_IP_address_or_DNS port_number

Note: Replace database_IP_address_or_DNS with the IP address or domain name of the database that you specify for the AWS DMS source or target endpoint. Replace port_number with the port number of the database that you specify for the AWS DMS source or target endpoint.

Then, run the following command:

nslookup domain_name

Note: Replace domain_name with the domain name of the database that you specify for the AWS DMS source or target endpoint.

Resolve native database errors

To resolve native database errors, confirm that you correctly set the following endpoint configurations:

• Username
• Password
• ServerName
  Note: You must set the ServerName to the DNS or IP address of the on-premises database, or Amazon Relational Database Service (Amazon RDS) endpoint.
• Port
• Database name
  Note: Don't specify a database name for a MySQL source or target.

If you use AWS Secrets Manager to specify any of the preceding fields, then see Using secrets to access AWS DMS endpoints.

Note: Secrets Manager doesn't support the following characters in passwords: semicolons ( ; ), periods ( . ), colons ( : ), plus signs ( + ), and curly brackets ( { } ).

For native database errors that relate to the source or target database, see the resolution from the specific database documentation. Use the error code and the error message that you receive in the AWS DMS console.

When you manually enter your credentials for endpoint configuration, make sure that you don't include curly brackets around your password. If you include curly brackets, then you receive error messages similar to the following:

Example error when Amazon Redshift is the target endpoint

"[SERVER ]E: RetCode: SQL_ERROR SqlState: 28000 NativeError: 10 Message: [Amazon][Amazon Redshift] (10) Error occurred while trying to connect: [SQLState 28000] connection to server at Your workgroup endpoint (IP), port 5439 failed: FATAL: password authentication failed for user Your Username [1022502] (ar_odbc_conn.c:614)"

Example error when MySQL is the target endpoint

"00012920: 2025-05-08T20:27:50:341649 [SERVER ]D: RetCode: SQL_ERROR SqlState: HY000 NativeError: 1045 Message: [MySQL][ODBC 8.0(w) Driver]Access denied for user UserName@IP (using password: YES) [1022502] (ar_odbc_conn.c:614)"

Example error when SQL Server is the target endpoint

"00012920: 2025-05-08T21:15:20:185761 [SERVER ]E: RetCode: SQL_ERROR SqlState: 28000 NativeError: 18456 Message: [Microsoft][ODBC Driver 17 for SQL Server][SQL Server]Login failed for user UserName. [1022502] (ar_odbc_conn.c:614)"

Note: If you use PostgreSQL as your target endpoint, then you can use curly brackets.

For more information, check the error, trace, alert, or other logs from the source or target database.

For database access errors, confirm the permissions that AWS DMS requires for the specific source or target.

For more information about how to encrypt connections for source and target endpoints with SSL, see Using SSL with AWS DMS.

Related information

How can I troubleshoot Amazon S3 endpoint connection test failures when using AWS DMS?

How can I troubleshoot connectivity failures and errors for an AWS DMS task that uses Amazon Redshift as the target endpoint?

How do I troubleshoot connectivity failures between AWS DMS and a MongoDB source endpoint?

Migrating Microsoft SQL Server databases to the AWS Cloud