Technology · PRACTICAL GUIDE
Linux says “File name too long”? Prove the path, component and data boundary first
Freeze the exact caller and argument, measure encoded bytes, query the real destination, and distinguish payload misuse from NAME_MAX and PATH_MAX before truncating anything.
“File name too long” is not one diagnosis. POSIX permits ENAMETOOLONG when one pathname component crosses NAME_MAX and when the whole pathname—or an intermediate result created while resolving symbolic links—crosses PATH_MAX. Application code can also trigger the same-looking failure by passing a JSON body, URL, certificate text or other payload to an API that expects a filename.
Do not start with a universal character cutoff. Freeze the exact API call and raw argument, decide whether the object is data or a path, measure encoded bytes per component and for the full path, query the actual destination, then change only the proven branch. Close the incident only after the original caller succeeds without silent truncation or name collision.
Freeze the exact caller and raw argument
Record the API or system call, exact exception and errno, timestamp, process or container, current working directory, destination mount, and a safe representation of the argument. Preserve length and a hash when the value may contain secrets; do not paste credentials, tokens or private content into logs.
Read the callee contract. Does it expect a pathname, bytes, a file object, a stream or already-parsed data? If the alleged filename begins with JSON, HTML, PEM markers, base64 or an entire URL response, stop measuring it as a path. Use the data, stream or parse interface that the library documents.
Measure bytes and split the pathname
For a genuine pathname, make it absolute in the failing context, split it on directory boundaries and measure the encoded bytes of every component. In Python, len(os.fsencode(component)) follows the filesystem encoding; len(text) counts characters and can understate multibyte names.
Record the longest component and the encoded byte length of the complete pathname separately. Keep generated prefixes, suffixes, extensions, percent-encoding and Unicode normalization visible: the application may expand a readable title into a much longer on-disk component.
Query the actual destination limits
Run getconf NAME_MAX /actual/parent and getconf PATH_MAX /actual/parent, or use os.pathconf(parent, "PC_NAME_MAX") and os.pathconf(parent, "PC_PATH_MAX") on Unix. Query the directory that will contain the entry, not an unrelated local filesystem or a guessed constant.
Interpret an unlimited or unsupported result carefully. Filesystems, network mounts, encryption layers and application APIs may impose tighter constraints. Preserve symlink and resolved-path evidence because an intermediate resolution can cross PATH_MAX even when the displayed input looks shorter.
Repair only the proven branch
If the object is data, replace the path-taking call with the correct parser, byte, stream or file-object API. If one component is too long, shorten only that generated component or replace its variable part with a deterministic collision-resistant identifier while preserving required suffixes and a lookup to the original value.
If the whole path is too long, shorten the controlled root or nesting structure; code that owns the traversal can sometimes use directory-relative APIs such as openat-style operations. Do not broadly catch every OSError, silently truncate user names or migrate storage before proving which boundary failed.
Replay the original caller and close the ledger
Repeat the original operation with the same input class, process context, working directory and destination. Verify create or open, write, fsync when relevant, read-back, close and cleanup. For generated names, test two inputs with the same prefix to prove that the fallback cannot collide.
Record the API contract, encoded lengths, queried limits, selected branch, mapping from original to stored identifier and acceptance result. If ENAMETOOLONG moves to another component or returns only in production, reopen the boundary ledger instead of adding another arbitrary cutoff.
