Troubleshooting
This section describes some common issues that might arise when using AWS Transfer Family and how to fix them.
Topics
- Troubleshoot Amazon EFS service-managed users
- Troubleshoot Amazon API Gateway issues
- Troubleshoot policies for encrypted Amazon S3 buckets
- Troubleshoot authentication issues
- Troubleshoot workflow-related errors using Amazon CloudWatch
- Troubleshoot workflow copy errors
- Troubleshoot missing POSIX profile
- Troubleshoot testing your identity provider
- Troubleshoot file upload issues
Troubleshoot Amazon EFS service-managed users
Description
You run the sftp
command and the prompt doesn't appear, and instead you
see the following message:
Couldn't canonicalize: Permission denied Need cwd
Cause
Your AWS Identity and Access Management (IAM) user's role does not have permission to access Amazon Elastic File System (Amazon EFS).
Solution
Increase the policy permissions for your user's role. You can add an AWS managed
policy, such as AmazonElasticFileSystemClientFullAccess
.
Troubleshoot Amazon API Gateway issues
This section describes possible solutions for the following issues:
Too many authentication failures
Description
When you try to connect to your server using Secure Shell (SSH) File Transfer Protocol (SFTP), you get the following error:
Received disconnect from 3.15.127.197 port 22:2: Too many authentication failures Authentication failed. Couldn't read packet: Connection reset by peer
Cause
You might have entered an incorrect password for your user. Try again to enter the correct password.
If the password is correct, the issue might be caused by a role Amazon Resource Name (ARN) that is not valid. To confirm that this is the issue, test the identity provider for your server. If you see a response similar to the following, the role ARN is a placeholder only, as indicated by the role ID value of all zeros:
{ "Response": "{\"Role\": \"arn:aws:iam::000000000000:role/MyUserS3AccessRole\",\"HomeDirectory\": \"/\"}", "StatusCode": 200, "Message": "", "Url": "https://
api-gateway-ID
.execute-api.us-east-1.amazonaws.com/prod/servers/transfer-server-ID
/users/myuser/config" }
Solution
Replace the placeholder role ARN with an actual role that has permission to access the server.
To update the role
-
Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation
. -
In the left navigation pane, choose Stacks.
-
In the Stacks list, choose your stack, and then choose the Parameters tab.
-
Choose Update. On the Update stack page, choose Use current template, and then choose Next.
-
Replace UserRoleArn with a role ARN that has sufficient permissions for accessing your Transfer Family server.
Note To grant the necessary permissions, you can add the
AmazonAPIGatewayAdministrator
and theAmazonS3FullAccess
managed policies to your role. -
Choose Next, and then choose Next again. On the Review
stack
page, select I acknowledge that AWS CloudFormation might create IAM resources, and then choose Update stack.
Connection closed
Description
When you try to connect to your server using Secure Shell (SSH) File Transfer Protocol (SFTP), you get the following error:
Connection closed
Cause
One possible cause for this issue is that your Amazon CloudWatch logging role does not have a trust relationship with Transfer Family.
Solution
Make sure that the logging role for the server has a trust relationship with Transfer Family. For more information, see To establish a trust relationship.
Troubleshoot policies for encrypted Amazon S3 buckets
Description
You have an encrypted Amazon S3 bucket that you are using as storage for your Transfer Family server.
If you try to upload a file to the server, you receive the error Couldn't close
file: Permission denied
.
And if you view the server logs, you see the following errors:
ERROR Message="Access denied" Operation=CLOSE Path=/bucket/user/test.txt BytesIn=13 ERROR Message="Access denied"
Cause
Your IAM user's policy does not have permission to access the encrypted bucket.
Solution
You must specify additional permissions in your policy to grant the required AWS Key Management Service (AWS KMS) permissions. For details, see Data encryption.
Troubleshoot authentication issues
This section describes possible solutions for the following issues:
Authentication failures—SSH/SFTP
Description
When you try to connect to your server using Secure Shell (SSH) File Transfer Protocol (SFTP), you receive a message similar to the following:
Received disconnect from 3.130.115.105 port 22:2: Too many authentication failures Authentication failed.
If you are using an API Gateway and receive this error, see Too many authentication failures.
Cause
You have not added an RSA key pair for your user, so you must authenticate using a password instead.
Solution
When you run the sftp
command, specify the -o
PubkeyAuthentication=no
option. This option forces the system to request your
password. For example:
sftp -o PubkeyAuthentication=no
sftp-user
@server-id
.server.transfer.region-id
.amazonaws.com
Miscellaneous authentication issues
Cause
If you receive an authentication error and none of the other troubleshooting works, you might have specified a target for a logical directory that contains a leading or trailing slash (/).
Solution
Update your logical directory target, to make sure it begins with a slash, and
does not contain a trailing slash. For example, /DOC-EXAMPLE-BUCKET/images
is
acceptable, while DOC-EXAMPLE-BUCKET/images
and /DOC-EXAMPLE-BUCKET/images/
are not.
Troubleshoot workflow-related errors using Amazon CloudWatch
Description
If you are having issues with your workflows, you can use Amazon CloudWatch to investigate the cause.
Cause
There can be several causes. Use Amazon CloudWatch Logs to investigate.
Solution
Transfer Family emits workflow execution status into CloudWatch Logs. The following types of workflow errors can appear in CloudWatch Logs:
-
"type": "StepErrored"
-
"type": "ExecutionErrored"
-
"type": "ExecutionThrottled"
You can filter your workflow's execution logs using different filter and pattern syntax. For example, you can create a log filter in your CloudWatch logs to capture workflow execution logs that contain the ExecutionErrored message. For details, see Real-time processing of log data with subscriptions and Filter and pattern syntax in the Amazon CloudWatch Logs User Guide.
StepErrored
2021-10-29T12:57:26.272-05:00 {"type":"StepErrored","details":{"errorType":"BAD_REQUEST","errorMessage":"Cannot tag Efs file","stepType":"TAG","stepName":"successful_tag_step"}, "workflowId":"w-abcdef01234567890","executionId":"1234abcd-56ef-78gh-90ij-1234klmno567", "transferDetails":{"serverId":"s-1234567890abcdef0","username":"lhr","sessionId":"1234567890abcdef0"}
Here, StepErrored
indicates that a step within the workflow has generated
an error. In a single workflow, you can have multiple steps configured. This error tells
you in which step the error occurred and provides an error message. In this particular
example, the step was configured to tag a file; however, tagging a file in an Amazon EFS file
system is not supported, so the step generated an error.
ExecutionErrored
2021-10-29T12:57:26.618-05:00 {"type":"ExecutionErrored","details":{},"workflowId":"w-w-abcdef01234567890", "executionId":"1234abcd-56ef-78gh-90ij-1234klmno567","transferDetails":{"serverId":"s-1234567890abcdef0", "username":"lhr","sessionId":"1234567890abcdef0"}}
When a workflow is not able to execute any step, it generates an ExecutionErrored
message.
For example, if you have configured a single step in a given workflow, and if the step is not able to execute, the overall workflow fails.
Executionthrottled
Execution is throttled if a workflow is getting triggered at a rate that is faster
than the system can support. This log message indicates that you must slow down your
execution rate for workflows. If you are not able to scale down your workflow-execution
rate, contact AWS Support at Contact
AWS
Troubleshoot workflow copy errors
Description
If you're executing a workflow that contains a step to copy the uploaded file, you could encounter the following error:
{ "type": "StepErrored", "details": { "errorType": "BAD_REQUEST", "errorMessage": "Bad Request (Service: Amazon S3; Status Code: 400; Error Code: 400 Bad Request; Request ID:
request-ID
; S3 Extended Request ID:request-ID
Proxy: null)", "stepType": "COPY", "stepName": "copy-step-name
" }, "workflowId": "workflow-ID
", "executionId": "execution-ID
", "transferDetails": { "serverId": "server-ID
", "username": "user-name
", "sessionId": "session-ID
" } }
Cause
The source file is in an Amazon S3 bucket that is in a different AWS Region than the destination bucket.
Solution
If you're executing a workflow that includes a copy step, make sure that the source and destination buckets are in the same AWS Region.
Troubleshoot missing POSIX profile
Description
If you're using Amazon EFS storage for your server and you're using a custom identity provider, you must provide your AWS Lambda function with a POSIX profile.
Cause
One possible cause is that the templates that we provide for creating an AWS Lambda-backed Amazon API Gateway method do not currently contain POSIX information.
If you did provide POSIX information, the format that you used for providing the POSIX information might not be getting parsed correctly by Transfer Family.
Solution
Make sure that you are providing a JSON element to Transfer Family for the
PosixProfile
parameter.
For example, if you're using Python, you could add the following line where you parse
the PosixProfile
parameter:
if PosixProfile: response_data["PosixProfile"] = json.loads(PosixProfile)
Or, in JavaScript, you could add the following line, where the
and
uid-value
are integers, 0 or greater,
that represent the User ID (UID) and Group ID (GID) respectively:gid-value
PosixProfile: {"Uid":
uid-value
, "Gid":gid-value
},
These code examples send the PosixProfile
parameter to Transfer Family as a JSON
object, rather than as a string.
Also, within AWS Secrets Manager, you must store the PosixProfile
parameter as
follows. Replace
and
your-uid
with your actual values for the
GID and UID.your-gid
{"Uid":
your-uid
, "Gid":your-gid
, "SecondaryGids": []}
Troubleshoot testing your identity provider
Description
If you test your identity provider using the console or the TestIdentityProvider
API call,
the returned message is blank.
Cause
The most likely cause is that the authentication failed because of an incorrect user name or password.
Solution
Make sure that you are using the correct credentials for your user, and make updates to the user name or password, if necessary.
Troubleshoot file upload issues
This section describes possible solutions for the following issues:
Troubleshoot Amazon S3 file upload errors
Description
When you are attempting to upload a file to Amazon S3 storage using Transfer Family, you receive the
following error message: AWS Transfer does not support random access writes
to S3 objects.
Cause
When you're using Amazon S3 for your server's storage, Transfer Family does not support multiple connections for a single transfer.
Solution
If your Transfer Family server is using Amazon S3 for its storage, disable any options for your client software that mention using multiple connections for a single transfer.
Troubleshoot unreadable filenames
Description
You see corrupted filenames in some of your uploaded files.
Cause
Users sometimes encounter problems with FTP and SFTP transfers that garble certain characters in filenames, such as umlauts, accented letters or completely different scripts like Chinese or Arabic. The problem is that while the FTP and SFTP protocols can allow for character encoding of files names to be negotiated by clients, Amazon S3 and Amazon EFS do not and require UTF-8 character encoding. The result: certain characters are not rendered correctly.
Solution
To solve this problem, review your client application for filename character encoding and make sure it is set to UTF-8.