Troubleshooting S3 Files
- 2.9k installs
- 2.2k repo stars
- Updated August 4, 2026
- aws/agent-toolkit-for-aws
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 mountin
About
The troubleshooting s3 files skill 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. Documentation covers workflows, commands, and guardrails agents should follow when users invoke this capability. Key documented areas include You MUST verify `aws` CLI is available with `s3files` subcommand support; You MUST confirm valid AWS credentials; You MUST ONLY check for tool existence and version - MUST NOT execute destructive or mutating commands during verification; You MUST inform the user if any required tools are missing. Reference commands include sudo yum -y install amazon-efs-utils # Amazon Linux; aws s3files list-mount-targets --file-system-id fs-ID --region REGION. Use when developers or agents need structured guidance for troubleshooting s3 files tasks with evidence grounded in the bundled SKILL.md rather than generic advice.
- You MUST verify `aws` CLI is available with `s3files` subcommand support
- You MUST confirm valid AWS credentials
- You MUST ONLY check for tool existence and version - MUST NOT execute destructive or mutating commands during verifica
- You MUST inform the user if any required tools are missing
- You MUST respect the user's decision to abort if tools are unavailable
Troubleshooting S3 Files by the numbers
- 2,860 all-time installs (skills.sh)
- +381 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #144 of 1,039 Cloud & Infrastructure skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
troubleshooting-s3-files capabilities & compatibility
- Capabilities
- you must verify `aws` cli is available with `s3f · you must confirm valid aws credentials · you must only check for tool existence and versi · you must inform the user if any required tools a · you must respect the user's decision to abort if
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill troubleshooting-s3-filesAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 2.9k |
|---|---|
| repo stars | ★ 2.2k |
| Security audit | 2 / 3 scanners passed |
| Last updated | August 4, 2026 |
| Repository | aws/agent-toolkit-for-aws ↗ |
How do I handle troubleshooting s3 files tasks with agent guidance?
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 mountin
Who is it for?
Teams needing documented troubleshooting s3 files workflows.
Skip if: Greenfield S3 bucket design, unrelated EBS volumes, or teams not using Amazon S3 Files POSIX mounts.
When should I use this skill?
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 mountin
What you get
Structured workflow from troubleshooting s3 files documentation applied to the user request.
- Diagnosis report
- Remediation steps for mount, IAM, sync, or performance
By the numbers
- Skill version 1 in aws/agent-toolkit-for-aws
Files
Troubleshooting S3 Files
Overview
Diagnoses and resolves Amazon S3 Files issues: mount failures, IAM permissions, synchronization, conflict resolution, and performance.
For authoritative guidance, see S3 Files Troubleshooting.
Common Tasks
0. Verify Dependencies
- You MUST verify
awsCLI is available withs3filessubcommand support - You MUST confirm valid AWS credentials
- You MUST ONLY check for tool existence and version — MUST NOT execute destructive or mutating commands during verification
- You MUST inform the user if any required tools are missing
- You MUST respect the user's decision to abort if tools are unavailable
- You SHOULD explain steps before executing and wait for user confirmation on write commands
1. Classify the Issue
| 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 |
2. Category A — Client Installation
mount.s3files: command not found means amazon-efs-utils is missing or < v3.0.0.
sudo yum -y install amazon-efs-utils # Amazon Linux3. Category B — Network/Security Group
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 REGIONCross-AZ mounting works but adds latency.
Verify security groups — most common fix:
- Mount target SG MUST have inbound TCP 2049 from compute SG
- Compute SG MUST have outbound TCP 2049 to mount target SG
- Fix:
aws ec2 authorize-security-group-ingress --group-id sg-MT --protocol tcp --port 2049 --source-group sg-COMPUTE
Test connectivity:
nc -zv az-ID.fs-ID.s3files.REGION.on.aws 2049Note: These SG troubleshooting steps also apply to EFS — use aws efs describe-mount-targets instead.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.
4. Category C — IAM Permissions
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 REGIONCheck 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 REGION5. Category D — Synchronization
Files not appearing in S3: Writes sync within ~60 seconds. Check status:
getfattr -n "user.s3files.status;$(date -u +%s)" filename --only-valuesCommon 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.
6. Category E — Conflict Resolution
Files in .s3files-lost+found-{fs-id} = sync conflict (modified via FS and S3 simultaneously). S3 wins; FS version moved to lost+found.
7. Category F — Performance
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.
8. Category G — Encryption/KMS
NFS server error with encrypted FS = KMS issue. Verify key is enabled and role has KMS permissions.
9. Category H — VPC DNS
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 enableDnsSupportBoth 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=trueTroubleshooting
AWS CLI endpoint URL cannot be resolved
CLI is too old for S3 Files. Run aws --version — if v1.x, upgrade to AWS CLI v2: Installing the AWS CLI.
ECS task fails with DNS resolution error
Used efsVolumeConfiguration instead of s3filesVolumeConfiguration. Fix: use fileSystemArn in S3 Files-specific volume config.
S3 Files vs other products confusion
S3 Files is NOT Mountpoint for S3, S3 File Gateway, or File Cache. Uses aws s3files CLI, s3files: IAM actions, mount -t s3files.
Enable Debug Logs
Set logging_level = DEBUG in /etc/amazon/efs/s3files-utils.conf. Logs at /var/log/amazon/efs/mount.log.
Collect Logs for AWS Support
sudo tar -czf /tmp/s3files-logs.tar.gz /var/log/amazon/efs/ /etc/amazon/efs/s3files-utils.confSecurity Considerations
- When diagnosing IAM issues, verify least-privilege — avoid FullAccess as a shortcut
- Without a file system policy, any VPC client can mount
- Restrict
/var/log/amazon/efs/access — logs contain S3 key names
Additional Resources
Related skills
Azure AiIntegrates Azure AI Content Safety, Document Intelligence, Speech, and Search services into Java-based agents and applications.495k1.4kAzure PrepareGenerate the exact Azure infrastructure files, Dockerfiles, and azure.yaml configuration needed before deploying any new or modernized application.494k1.4kAzure StorageConnect agents and applications to Azure Blob Storage, File Shares, Queues, Tables, and Data Lake without leaving the coding environment.494k1.4kAppinsights InstrumentationAutomatically instrument web applications running on Azure App Service with Application Insights for observability without manual configuration.493k1.4kAzure Resource LookupInstantly list, query, and discover any Azure resources across subscriptions without leaving the agent chat.493k1.4kAzure AigatewayConfigure Azure API Management as a secure, governed gateway for routing traffic to LLMs, MCP servers, and agent tools.493k1.4kHow it compares
Pick this over generic S3 bucket skills when the workload uses Amazon S3 Files POSIX mounts with sync and mount-specific failure modes.
FAQ
What does troubleshooting s3 files do?
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 mountin
When should I invoke 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 mountin
What are key capabilities?
You MUST verify `aws` CLI is available with `s3files` subcommand support
Is Troubleshooting S3 Files safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.