Object Storage Service:ossfs 2.0 FAQ

Mount error: Failed to mount ossfs2

Problem analysis: This is a general error. Check the logs for specific details. This error is typically caused by incorrect permissions or invalid configuration parameters. For example:

2025/03/21 15:09:59.124152|ERROR|th=00007F1238FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: AccessDenied

The AccessKey used lacks permissions to access the bucket. Verify that your AccessKey has the required permissions and that the bucket name is correct.

2025/03/21 15:14:29.671470|ERROR|th=00007F2304FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: InvalidAccessKeyId

The AccessKey you configured is invalid.

2025/03/21 15:15:13.805814|ERROR|th=00007FD591D38780|ossfs_v2.cpp:1469|Check bucket failed with err: SignatureDoesNotMatch

Solution: Correct the configuration based on the error message in the logs, and then mount again.

Mount error: Directory does not exist

Problem analysis: The specified directory does not exist.

Solution: Create the directory, and then run the mount command again.

Mount error: Directory is not empty

Problem analysis: ossfs 2.0 requires an empty mount target directory, but the specified one is not.

Solution: Check if another file system is already mounted to the directory. If so, unmount the file system with the umount command. If no other file system is mounted, remove any residual files from the directory. Alternatively, mount to a different empty directory.

Mount error: version FUSE_3.12' not found

Problem analysis: Required installation files are missing, causing ossfs 2.0 to fall back to the system-installed libfuse library, which is outdated.

Solution: Uninstall the package and then reinstall it.

Mount error: Fuse device not found

Problem analysis: The /dev/fuse device is not accessible. This issue typically occurs in a container environment that lacks the required access permissions.

Solution: When mounting in a container, start it in privileged mode.

Write error: File too large

Problem analysis: By default, ossfs 2.0 uses a part size of 8 MiB, which supports a maximum file size of 78.125 GiB. This error occurs when writing a file larger than this limit.

Solution: When you mount a Bucket, you can configure the upload_buffer_size option to increase the maximum supported file size. Please note that configuring upload_buffer_size requires more memory resources. ossfs 2.0 supports the total_mem_limit option to control memory usage. For more information, see Mount options.

Write error: Invalid argument

Problem analysis: ossfs 2.0 does not support random writes. It only supports sequential writes that append data to the end of a file. If you write to any position other than the current end of the file, ossfs 2.0 reports an "Invalid argument" error. The following log shows an example:

2025/04/14 11:00:39.307250|INFO |th=00007FEB88011870|fs.cpp:877|open file /fio/random-write-file.0.0
  nodeid: 5, flags: 32770, read_only: 0, truncate: 0, append: 0
2025/04/14 11:00:39.307551|ERROR|th=00007FEB88011DB0|file.cpp:294|append only file size: 0, offset: 63963136, write_off_: 0

Solution: If your application requires random writes, switch to ossfs 1.0. In many cases, what appear to be random writes are actually concurrent writes to the same file handle. If so, switch to single-threaded sequential writes. ossfs 2.0 is optimized for sequential writes and provides high throughput with a single thread.

git clone fails in the mount target

Problem analysis: By default, ossfs 2.0 does not support concurrent reads and writes on the same file. Reading a file while it is being written may return stale data or cause a read error. The git clone command uses a read-while-write access pattern, which may generate log entries similar to the following:

2025/03/21 14:50:52.412572|ERROR|th=00007FE970FF4940|file.cpp:1385|src file /libfuse/.git/objects/pack/tmp_pack_PFRsQf read failed, read : -1, expectRead : 1048576, size_ : 4556308, offset : 0, errno: 2

In the log, errno 2 is the Linux error code ENOENT, which indicates that the file data was not read correctly. If you encounter read errors with other applications, check the logs for similar messages. If a read operation fails without returning a "file not found" error, this can happen if the application has not closed the file, preventing its upload to OSS.

Solution: Avoid using the related commands. You can git clone to a local disk and then use the cp command to copy the files to the mount target.

Concurrent writes to the same file fail

Problem analysis: When multiple file handles are open for the same file in ossfs 2.0, only one handle supports sequential writes. Write operations from other file handles will fail. The following log shows an example of the error:

2025/03/21 14:59:22.765822|ERROR|th=00007FE990006990|file.cpp:231|file 181 has already been written!

Solution: Avoid concurrent writes to the same file. ossfs 2.0 is optimized for sequential writes, and a single thread can provide high throughput.

Unmount error: Target is busy

Problem analysis: A process accessing a file in the /mnt/ossfs2 mount target directory is blocking the unmount operation.

Solution:

1. Use the lsof /mnt/ossfs2 command to find the processes that are accessing the directory.

2. Stop the process.

3. Run the unmount command again.

Numerous 404 errors in logs

Background information: 404 Not Found entries are common in ossfs 2.0 logs. In most cases, they are not system errors but expected behavior that allows ossfs 2.0 to emulate local file system semantics.

Before performing an operation on a file, the operating system checks whether the target object exists. This check can trigger numerous probe requests to OSS. If an object does not exist, OSS returns a 404 status code.

The following steps describe the complete process ossfs 2.0 uses to check if an object exists:

1. Send a GetObjectMeta request to determine whether a specified path, such as object, exists as an actual object.

   If the object exists, the system returns its metadata. If the object does not exist, the system returns a 404 error and proceeds to the next step.

   Note

   Even if the object does not exist, ossfs 2.0 still needs to determine if the path is a directory.

2. After you receive a 404 error, send a ListObjects request to determine if the specified path is a 'directory', that is, to query for objects with the prefix object/.

   If the result is empty, the path does not exist. If the result is not empty, the directory exists, and the system lists its contents.

Problem analysis:

• When you use a command such as stat to access a non-existent file, the system returns a 404 error, which maps to the "No such file or directory" error of the local file system.

• Before creating files or directories in batches, the operating system checks if the target files or directories exist. It sends a create request only if they do not exist. The 404 errors generated during this check are expected behavior and do not indicate a system failure.

Solution: Although 404 errors are expected, frequent probe requests in high-concurrency or batch-operation scenarios can affect performance. You can use the following options to optimize performance:

1. Increase --attr_timeout to extend the metadata cache duration. The default duration is 60 s.

   Querying a file or directory before its metadata expires avoids repeated OSS requests.

2. Configure --oss_negative_cache_size and --oss_negative_cache_timeout to enable the negative cache.

   When a non-existent file is queried for the first time, the result is cached in memory. Subsequent queries for the same file are served from the local negative cache until it expires, avoiding further requests to OSS.

   • --oss_negative_cache_size: The number of entries in the negative cache for OSS files. The default value is 10,000.

   • --oss_negative_cache_timeout: The timeout for the OSS file negative cache. The default value is 0.