> ## Documentation Index > Fetch the complete documentation index at: https://docs.archil.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Solutions to common issues with Archil disks ## Problem: Mount fails with "No such file or directory" ``` ✗ Unable to mount Archil disk to '/mnt/archil': No such file or directory (os error 2) ``` The mount point must already exist as an empty directory before running `archil mount`. Create it first: ```bash theme={null} sudo mkdir -p /mnt/archil sudo archil mount /mnt/archil --region aws-us-east-1 ``` If the directory already exists and you still see this error, confirm you are passing the path exactly as it appears on disk (no typos, no trailing characters) and that a parent directory in the path is not itself a stale Archil mount. ## Problem: Mount fails with permission denied The Archil client cannot authenticate against the disk. This usually means the [disk token](/concepts/disk-users#disk-token-authorization) is wrong or has been regenerated, or the IAM role is not listed as an authorized disk user. ```bash theme={null} # Verify your IAM identity archil utils get-iam-role ``` Compare the output ARN to the **Authorized Users** list on the disk's Details page in the [Archil console](https://console.archil.com). If you are using disk token authentication, regenerate the disk token from the console — Archil does not store disk tokens in plaintext, so a lost token cannot be recovered. When passing a disk token through sudo, use `sudo --preserve-env=ARCHIL_MOUNT_TOKEN` so the variable is available to the Archil process. Using `sudo` alone drops the environment. ## Problem: Mount hangs or times out The client cannot reach the Archil control plane. Common causes are a wrong region, a network connectivity issue, or DNS resolution failure. ```bash theme={null} # Confirm the region matches the disk's region shown in the console sudo archil mount /mnt/data --region aws-us-east-1 # Test connectivity to the Archil control server curl -v https://mount.green.us-east-1.aws.prod.archil.com:8100 2>&1 | head -20 ``` Ensure your security groups or firewall rules allow outbound traffic on ports 8100 and 5000-5002. If you are running inside a VPC without public internet access, verify that DNS resolution is working and that a NAT gateway or VPC endpoint is configured. ## Problem: Files not appearing in S3 This is expected behavior. Archil provides [eventual synchronization consistency](/details/consistency) between the disk and the backing data source. Writes sync to S3 within a few minutes, not instantly. ```bash theme={null} # Verify the disk is healthy and accepting writes archil status /mnt/data ``` ## Problem: Another client cannot write to files Only one Archil client can have write ownership (a "delegation") over any given file or directory at a time. When a client mounts without `--shared`, it checks out the entire root, blocking all other clients from writing. Mounting that same disk from a second location will also fail outright, since the first client holds the root delegation — pass `--shared` on every mount to allow concurrent access. **Solutions:** ```bash theme={null} # Option 1: Mount both clients in shared mode and partition by directory sudo archil mount /mnt/data --region aws-us-east-1 --shared archil checkout /mnt/data/my-dir/ # Option 2: Use subdirectory mounts so each client owns a different subtree sudo archil mount :/models /mnt/models --region aws-us-east-1 # Client A sudo archil mount :/data /mnt/data --region aws-us-east-1 # Client B # Option 3: Force-claim ownership (use with caution) archil checkout /mnt/data/contested-dir/ --force ``` `--force` immediately revokes another client's delegation. Any unflushed writes from that client will be lost and subsequent `fsync` calls will return `EIO`. ## Problem: Permission denied when accessing files This is expected. The Archil FUSE client mounts as root, so all files start with root ownership. ```bash theme={null} # Change ownership to your user sudo chown -R $USER:$USER /mnt/data # Or run commands with sudo sudo ls /mnt/data ``` ## Problem: There's a `.archil` directory at the root of my mount Every Archil disk has a hidden `.archil/` directory at its root. Archil uses it to hold data that still needs to exist on the disk but is no longer reachable through the normal filesystem — most commonly, files that have been unlinked while a client still has them open. POSIX requires those files to keep working until the last handle is closed, so Archil parks them under `.archil/` until they can be reclaimed. The directory and its contents synchronize back to your backing S3 bucket along with the rest of the disk, so you'll see a `.archil/` prefix there as well. The exact layout is an implementation detail and may change between releases. Treat it as opaque: don't read from, write to, or delete anything inside `.archil/`, either on the mount or in S3. ## Problem: Data not appearing after writing to S3 directly Objects created directly in S3 (or another backing store) are subject to [eventual synchronization consistency](/details/consistency). It can take a few minutes for new objects to appear on the Archil disk. To get faster updates, reduce the directory cache expiry: ```bash theme={null} # Set cache expiry to 0 seconds for near-real-time visibility archil set-cache-expiry /mnt/data/incoming --readdir-expiry 0 # Or use a short TTL for a performance/freshness balance archil set-cache-expiry /mnt/data/incoming --readdir-expiry 5 ``` Lower cache expiry values improve freshness but increase the number of requests to the Archil server, which may affect read performance. ## Problem: SDK connection fails The TypeScript SDK cannot connect to the disk. Check the following: ```typescript theme={null} const client = await ArchilClient.connect({ region: "aws-us-east-1", // Must match the disk's region diskName: "myorg/mydisk", // Format: org/disk-name or disk ID authToken: process.env.ARCHIL_DISK_TOKEN, // Disk token; required outside AWS }); ``` 1. **Credentials** — Ensure a valid [disk token](/concepts/disk-users#disk-token-authorization) is set in `ARCHIL_DISK_TOKEN`, or that IAM credentials are available (e.g., running on EC2 with an attached role). Note that a disk token is different from a Control Plane API key. 2. **Disk name** -- Use the owner-qualified format `org/disk-name`, not just the disk name alone. 3. **Region** -- The region string must match exactly (e.g., `aws-us-east-1`, not `us-east-1`). 4. **Node.js version** -- The native module requires Node.js 18 or later.