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