# Frequently Asked Questions

## Applicable to all mount failures

Mount with `-f` to run US3FS in the foreground so you can directly inspect errors from stdout.

## Mount failed with “internal error” in logs

If the region does not support list service (ListObjects API not supported), remount with `--gfl`.

## 403 during mount

- If `ErrMsg` shows `"action not allow"`, check token permissions, add the missing permissions, and retry after ~5 minutes.
- If `ErrMsg` shows `"invlid signature"`, first verify your config fields, then check whether the token keys were copied completely.

## Error when remounting after abnormal exit

1. Run: `umount <mountpoint>`. If it fails, go to step 2.
2. Run: `sudo umount <mountpoint>`. If it still fails, contact technical support.

## Read/write errors

If you see errors like `"Input/Output error"`, do the following:

1. Check system logs:
   - CentOS: `/var/log/message`
   - Ubuntu: `/var/log/syslog`
2. If you find HTTP 500 errors in the logs, contact technical support to investigate.

## Other users cannot access the mount after mounting as the current user

Add `-o allow_other`.

## Mounted view differs from console

This is usually caused by `entry_timeout`, `attr_timeout`, and `dcache_timeout` being enabled by default with a 5-minute TTL. If you are sensitive to consistency, set them to `0s` to disable caching.

## How to reduce read/write latency
- Use large write I/O when possible (>=128KiB; >=1MiB can improve throughput if memory allows) and keep 4KiB alignment.
- For large file writes, increase `parallel` to improve throughput.
- For sequential reads of large files, set `readahead` (e.g., `32m`).
- Enable `wb` (writeback) to reduce kernel/user context switches and improve write speed, but files written with `wb` cannot be overwritten.
- For many non-hot small files (<256KiB) sequential/random reads, and random reads of large files, consider `direct_read`.
- For hot small files (<256KiB) sequential/random reads, do not enable `direct_read`.
- For high IOPS workloads, use async I/O with DirectIO, and tune `max_background` and `congestion_threshold`.
- Enable `keep_pagecache` to use VFS pagecache (significant for hot files / static assets).
- Enable `skip_ne_dir_lookup` to reduce lookup latency.

## High memory usage leading to OOM

If US3FS exits unexpectedly, it is often due to insufficient memory. Check system logs for OOM messages like:

```
earlyoom: low memory! at or below SIGKILL limits: mem  2.00%, swap 100.00%
earlyoom: sending SIGKILL to process 5637 uid 0 "us3fs": badness 671, VmRSS 2550 MiB
```

Suggested solutions:

- Use a machine with more memory for best performance.
- If performance is not critical, reduce `parallel` (default 32) to reduce concurrency and memory usage.
- If memory is tight, set `entry_timeout`, `attr_timeout`, `dcache_timeout` to `0s`.
- If `readahead` is enabled, ensure it is not too large and reduce it if necessary.
- If you are not doing sequential reads of large files, consider enabling `direct_read`.

## Directory exists in console but not shown under the mountpoint

This indicates a virtual directory. Create it under the mountpoint with `mkdir <dir>` to make it visible.

Virtual directory detection is enabled by default since v1.5.4; to disable it, set `disable_check_vdir`.

## System logs show “too many open files”

This may happen under heavy random I/O reads. Increase the per-process open file descriptor limit (often 1024 by default). Check with `ulimit -a` and set `open files` to 65535 or higher.

- For the current shell only: `ulimit -n 65535; <us3fs mount command>`
- System-wide: refer to [Too many open files](https://askubuntu.com/questions/1182021/too-many-open-files)