AWS DataSync
User Guide

Troubleshooting AWS DataSync Issues

Following, you can find information on how to troubleshoot AWS DataSync issues.

You Need DataSync to Use a Specific NFS or SMB Version to Mount Your Share

DataSync automatically selects the Network File System (NFS) or Server Message Block (SMB) version that is used to access your location. If you need DataSync to use a specific version, use the DataSync API or the AWS CLI. For SMB, you also can choose the version from the DataSync console.

Action to Take

To force DataSync to choose a specific NFS version, use the optional Version parameter for the CreateLocationNfs API operation, described in the DataSync API Reference.

To force DataSync to choose a specific SMB version, use the optional Version parameter for the CreateLocationSmb API operation, described in the DataSync API Reference.

The following AWS CLI commands create an NFS source location and force DataSync to use NFS version 4.0.

$ aws datasync create-location-nfs --server-hostname your-server-address --on-prem-config AgentArns=your-agent-arns --subdirectory nfs-export-path --mount-options Version=NFS4_0

The following AWS CLI commands create an SMB source location and force DataSync to use SMB version 3.

$ aws datasync create-location-smb --server-hostname your-server-address --on-prem-config AgentArns=your-agent-arns --subdirectory smb-export-path --mount-options Version=SMB3

You Get a "Failed to Retrieve Agent Activation Key" Error

When you are activating your DataSync agent, the agent connects to the specified endpoint to request an activation key. You can get this error in non-VPC endpoint use cases. For example, when your agent is deployed on-premises and your firewall settings block the connection. You can also get this error if your agent is deployed as an Amazon EC2 instance and the security groups are locked down.

Action to Take

Verify that your security group is set up to allow your agent to connect to the VPC endpoint and that you have allowed the required ports. For information about required ports, see Network Requirements.

Also, check your firewall and router settings and make sure that they allow communication with endpoints in AWS. For information about endpoint communication, see Giving Access Through Firewalls and Routers.

You Can't Activate an Agent Created Using a VPC Endpoint

If you are having issues when you are activating an agent that is created using a VPC endpoint, open a support channel against your VPC endpoint ENI. For information about Support Channel, see Enabling AWS Support to Help Troubleshoot Your Running On-Premises Agent.

Your Task Status Is Unavailable and Status Indicates a Mount Error

When you create a task, your task status might transition from CREATING to UNAVAILABLE when the agent that you chose can't mount the location that you specified during configuration.

Action to Take

First, make sure that the NFS server and export that you specified are both valid. If they aren't, delete the task, create a new one using the correct NFS server, and then export. For information more information, see Create an NFS Location.

If the NFS server and export are both valid, it generally indicates one of two things. Either a firewall is preventing the agent from mounting the NFS server, or the NFS server isn't configured to allow the agent to mount it.

Make sure that there is no firewall between the agent and the NFS server. Then make sure that the NFS server is configured to allow the agent to mount the export end specified in the task. For information about network and firewall requirements, see Network Requirements.

If you perform these actions and the agent still can't mount the NFS server and export, open a support channel and engage AWS Support. For information about how to open a support channel, see Enabling AWS Support to Help Troubleshoot Your Running On-Premises Agent.

Your Task Execution Fails with an Input/Output Error Message

You can get an Input/Output Error error message if your NFS server fails I/O requests that are issued by the DataSync agent. This can occur for reasons such as disk failure on the NFS server, changes in firewall configuration, and a network router failure.

Action to Take

First, check your NFS server's logs and metrics to determine if the problem started on the NFS server. If yes, resolve the issue that you discover.

Next, check that your network configuration hasn't changed. To check if the NFS server is configured correctly and accessible to DataSync through the network, do the following:

  1. Set up another NFS client on the same network subnet as the DataSync agent.

  2. Mount your share on that client.

  3. Validate that the client can read and write to the share successfully.

Your Task Execution is Stuck in Launching Status

Your task execution can become stuck in LAUNCHING status when DataSync can't instruct the specified source agent to begin a task. This issue usually occurs because the agent either is powered off or has lost network connectivity.

Action to Take

Make sure that the agent is connected and the status is ONLINE. If the status is OFFLINE, then the agent is not connected. For information about how to test network connectivity, see Testing Your Agent Connection to the Internet.

Next, make sure that your agent is powered on. If it isn't, power it on.

If the agent is powered on and the task is still stuck in LAUNCHING status, then a network connectivity problem between the agent and DataSync is the most likely issue. Check your network and firewall settings to make sure that the agent can connect to DataSync.

If you perform these actions and the issue isn't resolved, open a support channel and engage AWS Support. For information about how to open a support channel, see Enabling AWS Support to Help Troubleshoot Your Running On-Premises Agent.

Your Task Execution Fails with a Permissions Denied Error Message

You can get a "permissions denied" error message if you configure your NFS server with root_squash or all_squash enabled and your files don't have all read access.

Action to Take

To fix this issue, you can configure the NFS export with no_root_squash. Or you can make sure that the permissions for all of the files that you want to transfer allow read access for all users. Doing either enables the agent to read the files. For the agent to access directories, you must additionally enable all-execute access.

To make sure that the directory can be mounted, first connect to any computer that has the same network configuration as your agent. Then run the following CLI command.

mount -t nfs -o nfsvers=<your nfs server version> <your nfs server name>:<the nfs export path you specified> <a new test folder on your computer>

If you perform these actions and the issue isn't resolved, contact AWS Support.

Preparing Status for a Task Execution Takes Longer Than Expected to Complete

The time DataSync spends in the PREPARING status depends on the number of files in both the source and destination file systems, and the performance of these file systems. When a task starts, DataSync performs a recursive directory listing to discover all files and file metadata in the source and destination file system. These listings are used to identify differences and determine what to copy. This process usually takes between a few minutes to a few hours. For more information, see Starting a Task.

Action to Take

You don't need to take any action. Wait for the PREPARING status to complete and status changes to TRANSFERRING. If the status doesn't change to TRANSFERRING status, contact AWS Support.

Verifying Status for a Task Execution Takes Longer Than Expected to Complete

The time DataSync spends in the VERIFYING status depends on a number of factors. These are the number of files, the total size of all files in the source and destination file systems, and the performance of these file systems. By default, Verification mode is enabled in the options setting. The verification DataSync performs includes a SHA256 checksum on all file content and an exact comparison of all file metadata.

Action to Take

You don't need to take any action. Wait for the VERIFYING status to complete. If the VERIFYING status doesn't complete, contact AWS Support.

Your Storage Cost Is Higher Than Expected

If your storage cost is higher then expected, it might be due to one or more of the following reasons:

  • DataSync uses the Amazon S3 multipart upload feature to upload objects to Amazon S3. This approach can result in unexpected storage charges for uploads that don't successfully complete.

  • Object versioning might be enabled on your S3 bucket. Object versioning results in Amazon S3 storing multiple copies of objects that have the same name.

Action to Take

In these cases, you can take the following steps:

  • If the issue relates to multipart uploads, configure a policy for multipart uploads for your S3 bucket to clean up incomplete multipart uploads to reduce storage cost. For more information, see the AWS blog post S3 Lifecycle Management Update – Support for Multipart Uploads and Delete Markers.

  • If the issue relates to object versioning, verify whether object versioning is enabled for your Amazon S3 bucket. If versioning is enabled, turn it off.

If you perform these actions and the issue isn't resolved, contact AWS Support. For information about how to contact AWS Support, see Getting Started with AWS Support.

How to Enable AWS Support to Help Troubleshoot Your Running On-Premises Agent

You can allow AWS Support to access your agent and assist you with troubleshooting agent issues. By default, AWS Support access to your DataSync is not enabled. You enable this access through the host's local console. To give AWS Support access to your DataSync, you first log in to the local console for the host then connect to the support server.

For instructions on how to open a support channel, see Enabling AWS Support to Help Troubleshoot Your Running On-Premises Agent.