3.4 KiB
date, commonlib-version, self-hosted-livesync-version, status
| date | commonlib-version | self-hosted-livesync-version | status |
|---|---|---|---|
| 2026-09-04 | 0.1.21 | 1.0.24 | unreleased |
Path component length compatibility
Purpose
File systems place limits on each file or folder name, rather than applying one common limit to an entire Vault-relative path. Those limits are also expressed in different units. Self-hosted LiveSync therefore treats 255 UTF-8 bytes as a focused Android and Linux compatibility warning, not as a universal definition of a valid path.
Basis for the 255-byte warning
- The Linux kernel documentation gives ext4 a maximum file-name length of 255 bytes.
- The F2FS on-disk header defines
F2FS_NAME_LENas 255 and stores names in byte arrays. - Android's MediaProvider uses a
MAX_FILENAME_BYTESvalue of 255 when building file names. Its source notes that emulated storage can write to ext4 through FUSE, where names are encoded as UTF-8. - Android 11 and later use FUSE for emulated storage, with requests passing through to the underlying file system.
Together, these provide a conservative compatibility boundary for file names which may reach Android or Linux storage. They do not show that every Android device, storage provider, or Linux file system has the same limit.
Why the rule is not universal
Other platforms describe component limits differently. Microsoft's file-system
comparison documents limits in
Unicode characters,
not UTF-8 bytes. Apple's HFS Plus format stores a name as up to
255 16-bit UniChar values.
Apple's APFS guidance discusses valid UTF-8 names, normalisation, and case
sensitivity, but does not establish a universal
255-byte component rule.
A name can consequently exceed 255 UTF-8 bytes and still work on one platform, or fail for another platform-specific reason while remaining below this boundary.
Product policy
Self-hosted LiveSync applies the warning as follows:
- split the Vault-relative path on
/and inspect each non-empty component; - measure each component after UTF-8 encoding;
- accept 255 bytes without this warning and warn at 256 bytes or more;
- identify every over-limit file or folder name in the active-file status;
- do not reject, truncate, or rename the path; and
- treat the result of the real storage operation as authoritative.
If a scan cannot process an individual file, its path is recorded in the verbose log and remains eligible for a later retry. Ordinary start-up may still become ready so that unaffected files can synchronise. Explicit Fetch and Rebuild operations retain strict scan completion because they establish an authoritative local or remote state.
This policy does not replace the existing checks for reserved characters, case collisions, ignore rules, or configured file-size limits.