Terminal
Terminal/Skill
Diagnoses Amazon S3 Files mount failures, access denied errors, files missing from S3 after writes, lost+found conflicts and slow performance, with CLI checks.
By Amazon Web Services
Works with
npx skills add aws/agent-toolkit-for-aws --skill troubleshooting-s3-filesDiagnoses and resolves Amazon S3 Files issues: mount failures, IAM permissions, synchronization, conflict resolution, and performance.
For authoritative guidance, see S3 Files Troubleshooting.
aws CLI is available with s3files subcommand support| Symptom | Category |
|---|---|
| mount.s3files: command not found | A: Client Installation |
| Connection timed out during mount | B: Network/Security Group |
| Mount hangs indefinitely (no timeout) | B: Network/Security Group |
| Access denied during mount | C: IAM Permissions |
| File system stuck in "creating" | C: IAM Permissions |
| Permission denied on file operations | C: IAM Permissions |
| Files not appearing in S3 after write | D: Synchronization |
| Files in .s3files-lost+found directory | E: Conflict Resolution |
| Slow reads or high latency | F: Performance |
| NFS server error | G: Encryption/KMS |
| DNS name resolution fails | H: VPC DNS |
mount.s3files: command not found means amazon-efs-utils is missing or < v3.0.0.
sudo yum -y install amazon-efs-utils # Amazon Linux
Connection timeout is the #1 mount failure — almost always security groups.
Verify mount target exists in the instance's AZ:
aws s3files list-mount-targets --file-system-id fs-ID --region REGION
Cross-AZ mounting works but adds latency.
Verify security groups — most common fix:
aws ec2 authorize-security-group-ingress --group-id sg-MT --protocol tcp --port 2049 --source-group sg-COMPUTETest connectivity:
nc -zv az-ID.fs-ID.s3files.REGION.on.aws 2049
Note: These SG troubleshooting steps also apply to EFS — use
aws efs describe-mount-targetsinstead.
Mount hangs in isolated VPC: If the VPC has no internet access, S3 Files requires a CloudWatch Logs VPC endpoint (com.amazonaws.REGION.logs) for mount to complete.
File system stuck in "creating" status:
S3 Files does NOT validate IAM role permissions at creation time. Wrong trust policy or missing permissions → stuck in creating with access denied in statusMessage.
Check status:
aws s3files get-file-system --file-system-id fs-ID --region REGION
Check statusMessage. If access denied, fix the IAM role and delete/recreate.
Mount access denied: Compute role needs s3files:ClientMount. For dev/test only, AmazonS3FilesClientFullAccess is acceptable — avoid in production.
Write permission denied: Compute role needs s3files:ClientWrite
Root access denied: Compute role needs s3files:ClientRootAccess. ⚠️ Bypasses POSIX permissions — prefer access points with scoped POSIX users.
Check file system policy:
aws s3files get-file-system-policy --file-system-id fs-ID --region REGION
Files not appearing in S3: Writes sync within ~60 seconds. Check status:
getfattr -n "user.s3files.status;$(date -u +%s)" filename --only-values
Common ExportError values:
| Error | Fix |
|---|---|
| S3AccessDenied | File system IAM role lacks S3 write permissions |
| S3BucketNotFound | Bucket deleted or renamed |
| RoleAssumptionFailed | Trust policy misconfigured |
| EncryptionKeyInaccessible | KMS key disabled or permissions revoked |
| PathTooLong | File path exceeds 1,024 byte S3 key limit |
Monitor: PendingExports CloudWatch metric. Growing = exceeds 800 files/sec rate.
Files in .s3files-lost+found-{fs-id} = sync conflict (modified via FS and S3 simultaneously). S3 wins; FS version moved to lost+found.
First access latency: Normal — first directory access imports metadata.
Intelligent read routing not working: Compute role needs s3:GetObject on the bucket.
Slow writes: If PendingExports growing, distribute across multiple file systems.
NFS server error with encrypted FS = KMS issue. Verify key is enabled and role has KMS permissions.
DNS resolution failure = VPC DNS settings disabled.
aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsHostnames
aws ec2 describe-vpc-attribute --vpc-id vpc-ID --attribute enableDnsSupport
Both MUST be true. If not:
aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-hostnames Value=true
aws ec2 modify-vpc-attribute --vpc-id vpc-ID --enable-dns-support Value=true
CLI is too old for S3 Files. Run aws --version — if v1.x, upgrade to AWS CLI v2: Installing the AWS CLI.
Used efsVolumeConfiguration instead of s3filesVolumeConfiguration. Fix: use fileSystemArn in S3 Files-specific volume config.
S3 Files is NOT Mountpoint for S3, S3 File Gateway, or File Cache. Uses aws s3files CLI, s3files: IAM actions, mount -t s3files.
Set logging_level = DEBUG in /etc/amazon/efs/s3files-utils.conf. Logs at /var/log/amazon/efs/mount.log.
sudo tar -czf /tmp/s3files-logs.tar.gz /var/log/amazon/efs/ /etc/amazon/efs/s3files-utils.conf
/var/log/amazon/efs/ access — logs contain S3 key names