Setting up S3 Files involves IAM roles, security groups, mount targets, and NFS configuration. Each piece can fail independently, and the error messages are not always obvious. These are the errors we hit during real testing on Amazon Linux 2023 with S3 Files GA, along with the exact fix for each.
This guide assumes you already have S3 Files configured or are following our guide to mounting S3 buckets as a file system on EC2. For a broader overview of how S3 Files works, pricing, and performance characteristics, see the complete S3 Files guide.
Tested April 2026 on Amazon Linux 2023 with S3 Files GA. Every error in this article was captured from real testing.
IAM Permission Errors
Most S3 Files failures trace back to missing IAM permissions. The service needs a surprisingly wide set of actions across S3, EventBridge, EC2, and IAM itself. Here are the specific errors and what to add.
“is not authorized to perform: s3:GetBucketNotification”
The full error looks like this:
Access denied: User: arn:aws:sts::123456789012:assumed-role/S3FilesAccessRole/i-0abc123def456 is not authorized to perform: s3:GetBucketNotification on resource: "arn:aws:s3:::my-s3files-bucket" because no identity-based policy allows the s3:GetBucketNotification actionThis shows up when you run aws s3files get-file-system and the file system is stuck in “creating” status with no sign of progress. The statusMessage field contains the error above.
The S3FilesAccessRole (the role assumed by the S3 Files service) is missing bucket notification permissions. S3 Files needs to set up event notifications on the bucket to detect object changes, and it cannot proceed without them.
Add these actions to the role’s IAM policy:
s3:GetBucketNotification
s3:PutBucketNotification
s3:GetBucketVersioning
s3:GetBucketLocation
s3:GetEncryptionConfigurationAfter updating the policy, delete the stuck file system and recreate it. S3 Files does not retry automatically once it hits an IAM error during creation.
“is not authorized to perform: events:ListRules”
The full error message:
Access denied: User: arn:aws:sts::123456789012:assumed-role/S3FilesAccessRole/i-0abc123def456 is not authorized to perform: events:ListRules on resource: arn:aws:events:us-east-1:123456789012:rule/* because no identity-based policy allows the events:ListRules actionSame symptom as the previous error: the file system sits in “creating” and never becomes available. S3 Files uses Amazon EventBridge internally to monitor bucket changes for cache synchronization. Without EventBridge permissions, it cannot set up the event rules it needs.
Add EventBridge permissions to the S3FilesAccessRole. At minimum, you need:
events:PutRule
events:DeleteRule
events:DescribeRule
events:PutTargets
events:RemoveTargets
events:ListRulesYou can also use events:* if you prefer a broader grant, though least-privilege is better practice. Delete and recreate the file system after fixing the policy.
“User is not authorized to perform that action on the specified resource” (CreateMountTarget)
This one is less descriptive than the others:
An error occurred (AccessDeniedException) when calling the CreateMountTarget operation: User is not authorized to perform that action on the specified resourceIt triggers when running aws s3files create-mount-target. Mount targets create elastic network interfaces (ENIs) in your VPC, so the calling principal needs EC2 networking permissions that are not included in most default roles.
Add these EC2 actions to the role attached to your EC2 instance (or whichever principal is calling the API):
ec2:CreateNetworkInterface
ec2:DeleteNetworkInterface
ec2:DescribeNetworkInterfaces
ec2:DescribeSubnets
ec2:DescribeSecurityGroups
ec2:DescribeVpcsNote that these permissions go on the calling role (your EC2 instance role), not on the S3FilesAccessRole.
“is not authorized to perform: iam:PassRole”
The error appears during file system creation:
An error occurred (AccessDeniedException) when calling the CreateFileSystem operation: User: arn:aws:sts::123456789012:assumed-role/EC2Role/i-0abc123def456 is not authorized to perform: iam:PassRole on the specified resourceWhen you create a file system with --role-arn, you are passing the S3FilesAccessRole to the S3 Files service. AWS requires an explicit iam:PassRole permission for this, scoped to the specific role and target service.
Add this statement to your EC2 instance role’s policy:
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::123456789012:role/S3FilesAccessRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "elasticfilesystem.amazonaws.com"
}
}
}The Condition block limits the scope so this role can only be passed to the EFS/S3 Files service, not to arbitrary AWS services. Replace 123456789012 with your actual account ID.
File System and Mount Target Errors
Once IAM is sorted, the next set of errors involves the file system lifecycle and mount target creation.
“File system is not in a valid state for mount target creation”
This happens when you try to create a mount target before the file system is ready:
An error occurred (ConflictException) when calling the CreateMountTarget operation: File system is not in a valid state for mount target creationThe file system must be in “available” status before mount targets can be created. Most of the time, a file system stuck in “creating” means one of the IAM errors above is blocking it silently.
Check the file system status and look for a statusMessage:
aws s3files get-file-system --file-system-id fs-0abc123def456 --region us-east-1The output includes a statusMessage field that usually contains the underlying IAM error. Fix the permission issue, then delete the broken file system and create a new one. S3 Files does not recover from a failed creation on its own.
“S3 versioning not enabled”
File system creation fails with a versioning error when the source S3 bucket does not have versioning turned on. S3 Files requires bucket versioning because it needs to track object versions for cache consistency.
Enable versioning on the bucket:
aws s3api put-bucket-versioning --bucket my-s3files-bucket --versioning-configuration Status=EnabledVerify it took effect:
aws s3api get-bucket-versioning --bucket my-s3files-bucketYou should see "Status": "Enabled" in the response. Then retry the file system creation.
Client-Side Errors
These errors show up on the EC2 instance when trying to mount or use S3 Files commands.
“mount.s3files: command not found”
Running sudo mount -t s3files returns a “command not found” error. The mount.s3files helper is part of the amazon-efs-utils package, starting from version 3.0.0. Either the package is not installed or the installed version is too old.
On Amazon Linux 2023, install or update the package:
sudo yum install -y amazon-efs-utilsOn Ubuntu or Debian, use the official installer script:
curl https://amazon-efs-utils.aws.com/efs-utils-installer.sh | sudo sh -s -- --installConfirm the installed version supports S3 Files:
mount.s3files --versionThe output must show version 3.0.0 or higher. Anything below that does not include the S3 Files mount helper.
“aws: [ERROR]: argument command: Invalid choice ‘s3files'”
If you see this when running any aws s3files command, your AWS CLI is too old. The s3files subcommand was added in AWS CLI v2.34.
Update to the latest version:
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
cd /tmp && unzip -q awscliv2.zip
sudo ./aws/install --updateConfirm the update:
aws --versionThe version number should be 2.34 or later. Close and reopen your terminal session if the old version persists in your PATH.
“Connection timed out” or mount hangs
Running sudo mount -t s3files fs-0abc123def456:/ /mnt/s3files either hangs indefinitely or eventually times out. This is a networking issue, not an IAM issue. Three things to check, in order of likelihood:
1. Mount target is in a different AZ than the EC2 instance. S3 Files mount targets are AZ-specific. If your EC2 instance is in us-east-1a but the mount target was created in us-east-1b, the mount will fail. Create a mount target in the same AZ as your instance.
2. Security group missing the NFS inbound rule. The security group attached to the mount target must allow inbound TCP port 2049 from the EC2 instance’s security group or CIDR. Verify with:
aws ec2 describe-security-groups --group-ids sg-0abc123 --query 'SecurityGroups[].IpPermissions' --output tableLook for an inbound rule on TCP port 2049. If missing, add it:
aws ec2 authorize-security-group-ingress --group-id sg-0abc123 --protocol tcp --port 2049 --source-group sg-0def4563. Mount target still in “creating” state. It takes a minute or two for mount targets to become available. Check the status:
aws s3files list-mount-targets --file-system-id fs-0abc123def456 --region us-east-1Wait until LifeCycleState shows “available” before attempting the mount.
Debugging Tips
When the error message alone is not enough to pinpoint the problem, these commands help narrow things down.
Check the file system status and any error messages in statusMessage:
aws s3files get-file-system --file-system-id fs-0abc123def456 --region us-east-1 --query '{Status: status, Message: statusMessage}'List all mount targets and their lifecycle states:
aws s3files list-mount-targets --file-system-id fs-0abc123def456 --region us-east-1Verify NFS connectivity from the EC2 instance to the mount target IP:
telnet 10.0.1.50 2049If the connection is refused or times out, it confirms a security group or subnet routing issue. A successful connection shows “Connected to 10.0.1.50”.
Check the mount options on an existing mount point:
findmnt -T /mnt/s3filesThis shows the filesystem type, source, and mount options. Useful for confirming the mount used the correct file system ID and NFS version.
CloudWatch metrics for S3 Files are available under the AWS/S3Files namespace. Check ClientConnections, DataReadIOBytes, and DataWriteIOBytes to confirm the file system is actually handling traffic after a successful mount.
Quick Reference: Required IAM Permissions
To save time on future setups, here is a consolidated view of the permissions needed across both roles. Getting all of these right upfront avoids the cycle of creating, failing, deleting, and recreating file systems.
S3FilesAccessRole (assumed by the S3 Files service):
s3:GetBucketNotification,s3:PutBucketNotification,s3:GetBucketVersioning,s3:GetBucketLocation,s3:GetEncryptionConfigurations3:GetObject,s3:ListBucket,s3:GetObjectVersionevents:PutRule,events:DeleteRule,events:DescribeRule,events:PutTargets,events:RemoveTargets,events:ListRules
EC2 Instance Role (the calling principal):
s3files:*(or scoped to CreateFileSystem, CreateMountTarget, etc.)ec2:CreateNetworkInterface,ec2:DeleteNetworkInterface,ec2:DescribeNetworkInterfaces,ec2:DescribeSubnets,ec2:DescribeSecurityGroups,ec2:DescribeVpcsiam:PassRole(scoped to the S3FilesAccessRole andelasticfilesystem.amazonaws.com)
For the full setup walkthrough including bucket creation, role configuration, and the mount process, see the EC2 mount guide. If you need to update your AWS CLI, our AWS CLI installation guide covers all platforms. The official AWS S3 Files troubleshooting documentation covers additional edge cases not included here.
