How do I troubleshoot AWS DMS endpoint connectivity failures?

9 minute read

I can't connect to my AWS Database Migration Service (AWS DMS) endpoints, and my test connection fails. I want to troubleshoot connectivity issues between my replication instance and source or target endpoints.

Resolution

A successful endpoint test connection requires network connectivity between the replication instance and the source or target database, along with valid database credentials and permissions.

If your replication can't reach the source or target database over the network, then you receive timeout or host resolution similar to the following.

Microsoft SQL Server error:

"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."

PostgreSQL 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."

MySQL 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 your endpoint credentials or permissions are incorrect, then you receive native database errors similar to the following:

If your test connection fails, identify whether the error is a network connectivity issue or a native database error.

Note: 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

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.

Check whether you can establish a connection between the source or target database and the 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 in the security group that allows traffic to the IP address and port of the source or target database.
An Outbound Rule in the network access control list (network ACL) that allows traffic to the IP address and port of the source or target database.
An Inbound Rule in the network ACL that allows return traffic on ephemeral ports 1024-65535 from the source or target database.
Note: By default, security group Outbound Rules and network ACL Inbound and Outbound Rules allow 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 in the security group for the IP address of the replication instance on database port.
An Inbound Rule in the network ACL for the IP address of the replication instance on the database port. Confirm that there's no explicit deny rule for the IP address and port.
An Outbound Rule in the network ACL for ephemeral ports 1024-65535 to the replication instance.
No explicit deny rule in the network ACL for the IP address of the replication instance.

By default, security group and network ACL rules allow all traffic. Security groups are stateful, so you can keep the default Outbound Rule. Use the CIDR block of the subnet group for the replication instance instead of a specific IP address. 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:

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

AWS CLI

Run the describe-replication-instances command to get the subnet IDs from the AWS DMS replication instance:

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.

Run the following describe-subnets AWS CLI command to get the CIDR block for those subnets:

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.

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.

Confirm 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

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.