troubleshooting-s3-files
Diagnoses and resolves Amazon S3 Files issues including mount failures, permission errors, synchronization problems, and performance issues. Use when the user has an S3 file system that is not mounting, returning access denied, not syncing changes to S3, showing files in lost+found, or performing slower than expected.
Security Assessment
Detected risks:
About troubleshooting-s3-files
Troubleshooting S3 Files diagnoses and resolves Amazon S3 Files problems: mount failures, IAM permission errors, synchronization issues, sync conflicts, and performance degradation. It is meant for situations where an S3 file system is not mounting, is returning access denied, is not syncing changes back to S3, is placing files in a lost+found directory, or is performing slower than expected. It points to the authoritative AWS S3 Files Troubleshooting documentation and organizes diagnosis around a symptom-to-category classification table.
The workflow begins by verifying dependencies — confirming the aws CLI supports the s3files subcommand and that valid AWS credentials exist — while restricting verification to non-destructive checks and respecting the user's choice to abort. It then classifies the issue into categories A through H and gives concrete remediation for each: Category A (client installation) fixes mount.s3files: command not found by installing amazon-efs-utils (v3.0.0+); Category B (network/security group) addresses connection timeouts by checking mount targets with aws s3files list-mount-targets, opening inbound/outbound TCP 2049 between security groups, testing with nc, and noting isolated VPCs need a CloudWatch Logs VPC endpoint; Category C (IAM) covers stuck creating status, s3files:ClientMount, s3files:ClientWrite, and s3files:ClientRootAccess; Category D (synchronization) uses getfattr to read export status and lists ExportError values like S3AccessDenied, S3BucketNotFound, RoleAssumptionFailed, EncryptionKeyInaccessible, and PathTooLong, with the PendingExports CloudWatch metric; Category E (conflict resolution) explains the .s3files-lost+found directory where S3 wins; Category F (performance); Category G (encryption/KMS); and Category H (VPC DNS) verifying enableDnsHostnames and enableDnsSupport.
The skill targets AWS engineers, SREs, and support staff working with S3 Files. It includes guidance for enabling debug logs (logging_level = DEBUG in /etc/amazon/efs/s3files-utils.conf, logs at /var/log/amazon/efs/mount.log), collecting logs for AWS Support, and security considerations such as least-privilege IAM and restricting log access because logs contain S3 key names. Requirements include AWS CLI v2 and correct s3filesVolumeConfiguration for ECS tasks.
FAQ
What symptoms does this skill help diagnose?
Mount failures (command not found, connection timeouts, hangs), access denied errors, file systems stuck in creating status, files not appearing in S3, files in the .s3files-lost+found directory, slow reads or writes, NFS/KMS errors, and DNS resolution failures. Each maps to categories A through H.
What are the prerequisites before troubleshooting?
You must verify the aws CLI is available with s3files subcommand support and confirm valid AWS credentials. Verification is limited to checking tool existence and version; destructive or mutating commands must not run during verification, and the user's decision to abort must be respected.
Why is a mount connection timing out?
Connection timeout is the number one mount failure and is almost always caused by security groups. The mount target security group must allow inbound TCP 2049 from the compute security group, and the compute security group must allow outbound TCP 2049 to the mount target.
How do I check why files are not syncing to S3?
Writes sync within about 60 seconds. Read the export status with getfattr on the file, then interpret ExportError values such as S3AccessDenied, S3BucketNotFound, RoleAssumptionFailed, EncryptionKeyInaccessible, or PathTooLong, and monitor the PendingExports CloudWatch metric.
Does this apply if my AWS CLI is old?
No. If the CLI cannot resolve the endpoint URL it is too old for S3 Files. Run aws --version, and if it is v1.x, upgrade to AWS CLI v2. S3 Files is distinct from Mountpoint for S3, S3 File Gateway, and File Cache.
Install troubleshooting-s3-files
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
aws/agent-toolkit-for-aws