Troubleshooting

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:

sudo mkdir -p /mnt/archil
sudo archil mount <disk-name> /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 is wrong or has been regenerated, or the IAM role is not listed as an authorized disk user.

# 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. 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.

# Confirm the region matches the disk's region shown in the console
sudo archil mount <disk-name> /mnt/archil --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: Mount fails because the client is no longer supported

If the mount fails with this version of the Archil client is no longer supported by the server, your client is older than the minimum version the server, your organization, or the disk requires. Upgrade the client with archil upgrade or rerun the installer, then retry the mount.

Problem: Files not appearing in S3

This is expected behavior. Archil provides eventual synchronization consistency between the disk and the backing data source. Writes are durable on the disk as soon as they are committed, and Archil copies them to S3 in the background, usually tens of seconds after a file’s last write. A file that keeps changing is copied within about 10 minutes. You can’t force the copy. If your S3 clients need to see writes immediately, use the Archil S3 API, which reads the disk directly.

# Verify the disk is healthy and accepting writes
archil status /mnt/archil

Problem: Another client doesn’t see my changes

Another client reads a change once it has reached the disk and the other client isn’t answering from an older cache entry. Check both sides:

On the writer, run fsync on the file, or archil sync /mnt/archil for the whole mount. On exclusive and shared mounts, close doesn’t wait for writes to reach the disk.
On the reader, open the file again; opening a file checks it with the disk. A new file can still be missing from a directory listing the reader cached, for up to five minutes by default. Run archil invalidate-cache /mnt/archil to drop the reader’s cache, or lower the listing lifetime with archil set-cache-expiry.

# Writer
sudo archil sync /mnt/archil

# Reader
sudo archil invalidate-cache /mnt/archil

See Consistency for the full rules.

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 or --conditional, it checks out the entire root, blocking all other clients from writing. A second mount without --shared, --conditional, or --read-only will fail outright, since the first client holds the root delegation — pass --shared or --conditional on every mount to allow concurrent writes, or --read-only on the other clients if only one client needs to write. Solutions:

# Option 1: Mount every client in conditional mode, so any client can write without a checkout
sudo archil mount <disk-name> /mnt/archil --region aws-us-east-1 --conditional

# Option 2: Mount both clients in shared mode and partition by directory
sudo archil mount <disk-name> /mnt/archil --region aws-us-east-1 --shared
archil checkout /mnt/archil/my-dir/

# Option 3: Use subdirectory mounts so each client owns a different subtree
sudo archil mount <disk-name>:/models /mnt/models --region aws-us-east-1   # Client A
sudo archil mount <disk-name>:/data   /mnt/archil   --region aws-us-east-1   # Client B

# Option 4: Keep one client as the only writer and mount the others read-only
sudo archil mount <disk-name> /mnt/archil --region aws-us-east-1               # Writer
sudo archil mount <disk-name> /mnt/archil --region aws-us-east-1 --read-only   # Each reader

# Option 5: Force-claim ownership (use with caution)
archil checkout /mnt/archil/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: Writes fail on a conditional mount

On a conditional mount, the archil client buffers recent writes and sends them to the disk in the background, so a write can succeed and then fail when it’s sent. There are two common causes:

Another client deleted the file. Writes to the file that hadn’t reached the disk are lost. Reads, writes, fsync, and close on file descriptors still open on that file return ESTALE. The rest of the mount keeps working.
Another client checked out the file or a directory above it with archil checkout, or mounted the disk without --shared or --conditional. The mount becomes read-only: writes that hadn’t reached the disk are lost, further writes return EROFS, and fsync and close return EIO. Reads keep working.

Creating, renaming, or deleting a file under a path another client has checked out fails immediately with EROFS, without affecting the rest of the mount. To recover a mount that has become read-only, unmount it and mount the disk again:

sudo archil unmount /mnt/archil
sudo archil mount <disk-name> /mnt/archil --region aws-us-east-1 --conditional

Writes to the path the other client checked out will keep failing until that client releases it with archil checkin or unmounts. To avoid this, don’t check out paths that clients in conditional mode are still writing to.

Problem: Permission denied when accessing files

This is expected. The Archil FUSE client mounts as root, so all files start with root ownership.

# Change ownership to your user
sudo chown -R $USER:$USER /mnt/archil

# Or run commands with sudo
sudo ls /mnt/archil

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. Archil lists a directory in the bucket again in the background when the directory is read and its listing is more than five minutes old, so it can take a few minutes for new objects to appear on the Archil disk. A mounted client also caches directory listings. To stop it from adding its own delay on top, reduce the directory cache expiry:

# List the directory from the disk on every read
archil set-cache-expiry /mnt/archil/incoming --readdir-expiry 0

# Or use a short TTL for a performance/freshness balance
archil set-cache-expiry /mnt/archil/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:

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
});

Credentials — Ensure a valid disk token 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.
Disk name — Use the owner-qualified format org/disk-name, not just the disk name alone.
Region — The region string must match exactly (e.g., aws-us-east-1, not us-east-1).
Node.js version — The native module requires Node.js 18 or later.

Getting started

Compute

Concepts

Data Sources

Details

Administration

Protocols

Reference

Legal

Troubleshooting

Problem: Mount fails with “No such file or directory”

Problem: Mount fails with permission denied

Problem: Mount hangs or times out

Problem: Mount fails because the client is no longer supported

Problem: Files not appearing in S3

Problem: Another client doesn’t see my changes

Problem: Another client cannot write to files

Problem: Writes fail on a conditional mount

Problem: Permission denied when accessing files

Problem: There’s a `.archil` directory at the root of my mount

Problem: Data not appearing after writing to S3 directly

Problem: SDK connection fails

​Problem: Mount fails with “No such file or directory”

​Problem: Mount fails with permission denied

​Problem: Mount hangs or times out

​Problem: Mount fails because the client is no longer supported

​Problem: Files not appearing in S3

​Problem: Another client doesn’t see my changes

​Problem: Another client cannot write to files

​Problem: Writes fail on a conditional mount

​Problem: Permission denied when accessing files

​Problem: There’s a .archil directory at the root of my mount

​Problem: Data not appearing after writing to S3 directly

​Problem: SDK connection fails

Problem: Mount fails with “No such file or directory”

Problem: Mount fails with permission denied

Problem: Mount hangs or times out

Problem: Mount fails because the client is no longer supported

Problem: Files not appearing in S3

Problem: Another client doesn’t see my changes

Problem: Another client cannot write to files

Problem: Writes fail on a conditional mount

Problem: Permission denied when accessing files

Problem: There’s a `.archil` directory at the root of my mount

Problem: Data not appearing after writing to S3 directly

Problem: SDK connection fails