A capacity error needs the right unit of measurement
A filesystem can have room for more file contents while lacking capacity for additional file records. On filesystems with a bounded inode supply, large numbers of small files can exhaust those records before the byte-capacity chart appears full. An inode holds filesystem metadata; it is not another name for a gigabyte.
Start with the exact failing operation and path. A web upload, a mail queue and a temporary build directory may live on different mounts. Increasing an unrelated disk or cleaning a convenient directory can leave the actual failure untouched. This guide concerns file-count capacity, not permission errors or a complete filesystem-repair procedure.
Setup: establish a safe diagnostic boundary
Record the affected mount, filesystem type, application owner and retention requirements. GNU df -h /affected/path examines block capacity, while df -i /affected/path examines inode usage. Use an existing parent directory when the intended new file does not exist. Check command errors rather than treating an incomplete report as evidence of available space.
GNU du --inodes -x --max-depth=1 /reviewed/directory can help locate high-file-count areas without crossing into other filesystems. Availability of options depends on the installed tool implementation. Large directory scans can add I/O load, so narrow the investigation before expanding it across a busy server.
Illustrative incident: a cache retains every temporary object
An illustrative application stores a separate temporary file for each completed import but never expires old objects. New imports eventually fail even though the byte-capacity dashboard looks comfortable. This scenario illustrates a retention defect and makes no claim about a real customer's workload or a measured storage saving.
Compare file-count growth with import completion and the expected cleanup schedule. Ask whether the files are regenerable cache entries, pending work, or the only retained evidence of a transaction. The answer determines who may approve removal and what records must be preserved.
Troubleshooting: choose the matching investigation
| Observation | Check | Interpretation to test |
|---|---|---|
| Block capacity looks healthy | Inode report for the same mount | File records may be the constrained resource |
| One directory dominates file count | Age, owner and application purpose | Retention or cleanup may be incomplete |
| Cleanup does not change the failing mount | Mount and namespace identity | The inspected path may be different |
| File creation fails with healthy capacity | Full error, quotas and permissions | The problem may not be inode exhaustion |
Container and host paths can describe different mount views. Keep the application namespace in the evidence. Also distinguish the count of names encountered during a directory walk from underlying allocation: hard links, snapshots and filesystem behavior can make simple totals misleading.
Correct retention without erasing business records
Agree a narrowly scoped retention action with the data owner. Preserve required evidence and remove only material whose lifecycle permits deletion. Use a bounded cleanup job and observe its effect; a broad recursive delete during an incident can turn a capacity problem into a recovery problem.
Repair the producing workflow as well as the accumulated files. Define expiration, ownership and failure reporting for cleanup. If legitimate steady-state file count exceeds the filesystem design, plan a migration or storage redesign with backup and restore checks rather than assuming a byte expansion will increase usable inode capacity in the required way.
Verification, capacity objective and SOP
Verify inode and block reports on the affected mount after the approved action. As the application identity, perform a disposable create-and-remove test in an authorized scratch location, then execute a representative business workflow. Confirm that pending jobs are still present and that cleanup has not removed their inputs.
Monitor file-count growth, cleanup failures and time remaining at the observed growth rate. An example SLO can track successful eligible file-creation workflows; set its target after measuring real demand. An external SLA requires a separate agreement. The SOP should name retention approval, excluded directories, cleanup limits, evidence handling and the condition for escalating to storage engineering.
See Clouvenix storage infrastructure for help defining a reviewed operational scope.
Technical reference
GNU df inode reporting, GNU file usage and du options. Reviewed 19 October 2026; select documentation matching the installed release.