Troubleshooting

Permission denied with a writable destination

Replacement needs permission to create and rename entries in the parent directory. Check directory ownership, mode, and mount flags. By tradition, the file is innocent until the directory proves otherwise.

Invalid JSON after a successful write

Latchfile commits bytes. It leaves format validation to the application. Validate the document before writing and check that stream encoders return any error from their final flush.

Old contents after a successful rename

Confirm the reader resolves the same absolute path. If it keeps an open handle, close and reopen it. For shared filesystems, check whether the client mounts use attribute caching.

Leftover temporary files

A forced process exit can interrupt cleanup. Only remove temporary files from a directory you control, once you have confirmed that no writer still owns them.