troubleshooting-s3-files

Diagnoses and resolves Amazon S3 Files mount, permission, sync, and performance issues.

Updated Jul 1, 2026
One-click install
npx skills add https://github.com/sakicodes/BuildFestHackathon26 --skill troubleshooting-s3-files-sakicodes
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: troubleshooting-s3-files
Source: https://github.com/sakicodes/BuildFestHackathon26/tree/main/.agents/skills/troubleshooting-s3-files
Command: npx skills add https://github.com/sakicodes/BuildFestHackathon26 --skill troubleshooting-s3-files-sakicodes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Amazon S3 Files deployments can fail in many ways—mount timeouts, access denied errors, files not syncing to S3, or unexpected latency—and finding the root cause requires checking security groups, IAM roles, KMS keys, and VPC DNS settings. This Skill provides a structured diagnostic workflow that classifies symptoms into categories and walks through the exact AWS CLI commands needed to identify and fix each issue. ## Core Features & Use Cases - Symptom-Based Classification: Maps common symptoms (mount failures, access denied, lost+found files, slow reads) to eight diagnostic categories covering client installation, networking, IAM, synchronization, conflicts, performance, encryption, and DNS. - Guided Remediation: Provides concrete AWS CLI commands for each category, such as verifying security group rules on port 2049, checking file system status messages, and inspecting sync errors via extended attributes. - Use Case: An engineer mounts an S3 Files file system and gets a connection timeout. The Skill identifies this as a security group issue, verifies the mount target exists in the instance's AZ, and provides the exact authorize-security-group-ingress command to allow TCP 2049 traffic. ## Quick Start Ask the assistant to troubleshoot why your S3 Files file system is not mounting or why files are not appearing in your S3 bucket.

Frequently Asked Questions about troubleshooting-s3-files

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix S3 Files mount connection timeout errors?

A connection timeout during mount is almost always a security group issue. Verify the mount target security group allows inbound TCP port 2049 from the compute security group, and that the compute group allows outbound TCP 2049 to the mount target.

Why is my S3 Files file system stuck in creating status?

S3 Files does not validate IAM role permissions at creation time, so a wrong trust policy or missing permissions leaves the file system stuck in creating. Run aws s3files get-file-system and check statusMessage for access denied, then fix the IAM role and recreate.

Why are files not appearing in S3 after writing to S3 Files?

Writes sync to S3 within about 60 seconds. Check the file's sync status with getfattr on the user.s3files.status attribute; common errors include S3AccessDenied, S3BucketNotFound, RoleAssumptionFailed, and PathTooLong for keys over 1,024 bytes.

What does the .s3files-lost+found directory mean?

Files in .s3files-lost+found indicate a sync conflict where the file was modified through both the file system and S3 simultaneously. The S3 version wins, and the file system version is moved to lost+found for recovery.

Does S3 Files mounting work in a VPC without internet access?

Yes, but an isolated VPC requires a CloudWatch Logs VPC endpoint (com.amazonaws.REGION.logs) for the mount to complete. Without it, the mount hangs indefinitely instead of timing out.

Is S3 Files the same as Mountpoint for S3 or S3 File Gateway?

No. S3 Files is a distinct service using the aws s3files CLI, s3files: IAM actions, and mount -t s3files. It is not Mountpoint for S3, S3 File Gateway, or File Cache, and troubleshooting steps differ between them.