Troubleshooting
This section describes some common issues that might arise when using AWS Transfer Family and how to fix them.
Topics
- Troubleshoot 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 ResourceNotFound exception
- Troubleshoot AS2 issues
Troubleshoot service-managed users
This section describes possible solutions for the following issues
Topics
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 public key body too long
Description
When you try to create a service-managed user, you receive the following error:
Failed to create user (1 validation error detected: 'sshPublicKeyBody' failed to satisfy constraint: Member must have length less than or equal to 2048)
Cause
You might be entering a PGP key for the public key body, and AWS Transfer Family does not support PGP keys for service-managed users.
Solution
If the PGP key is RSA-based, you can convert it to PEM format. For example, Ubuntu provides a conversion tool here:
https://manpages.ubuntu.com/manpages/xenial/man1/openpgp2ssh.1.html
Troubleshoot failed to add SSH public key
Description
When you try to add a public key for a service-managed user, you receive the following error:
Failed to add SSH public key (Unsupported or invalid SSH public key format)
Cause
You might be attempting to import an SSH2-formatted public key, and AWS Transfer Family does not support SSH2-formatted public keys for service-managed users.
Solution
You need to convert the key into OpenSSH format. This process is described in Convert an SSH2 public key to OpenSSH format.
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
The policy for your IAM user 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 in Amazon S3.
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"
-
"Service failure on starting workflow"
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
Service failure on starting workflow
Anytime you remove a workflow from a server and replace it with a new one, or update server configuration (which impacts a workflow's execution role), you must wait approximately 10 minutes before executing the new workflow. The Transfer Family server caches the workflow details, and it takes 10 minutes for the server to refresh its cache.
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 username 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 file names
Description
You see corrupted file names in some of your uploaded files. Users sometimes encounter problems with FTP and SFTP transfers that garble certain characters in file names, such as umlauts, accented letters, or certain scripts, such as Chinese or Arabic.
Cause
Although 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. Instead, they require UTF-8 character encoding. As a result, certain characters are not rendered correctly.
Solution
To solve this problem, review your client application for file name character encoding and make sure it is set to UTF-8.
Troubleshoot ResourceNotFound
exception
Description
You receive an error where the resource cannot be found. For example, if you run UpdateServer
, you might get the following error:
An error occurred (ResourceNotFoundException) when calling the UpdateServer operation: Unknown server
Cause
There are several reasons for receiving a ResourceNotFoundException
message. In most cases, the resource that
you specified in your API command does not exist. If you did specify an existing resource, then the most probable cause is that
your default region is different than the region for your resource. For example, if your default region is us-east-1, and your Transfer Family
server is in us-east-2, you will receive an Unknown resource
exception.
For details about setting a default region, see Quick configuration with aws configure
.
Solution
Add a region parameter to your API command to explicitly specify where to find a particular resource.
aws transfer -describe-server --server-id
server-id
--region us-east-2
Troubleshoot AS2 issues
Error messages and troubleshooting tips for Applicability Statement 2 (AS2)-enabled servers are described here: AS2 error codes.