FileStorage does not use atomic write

[JanTvrdik]

Couple of times per month I receive unserialize error ("Error at offset X of Y bytes") from RobotLoader which uses FileStorage. This suggests that FileStorage failed to write tha data properly. I alway delete the cache which solves the issue, obviously, but it is getting quite annoying so I've decided to finally open this issue.

Windows 10 x64, PHP 7.0.8 x64 NTS, FastCGI + Caddy

[dg]

I have never experienced such a problem.

[podolinek]

Similar bug for me, whole notice: PHP Notice: unserialize(): Error at offset 18 of 34 bytes in /project_dir/vendor/nette/caching/src/Caching/Storages/FileStorage.php:339 . It everytime occurs at the same page. Maybe some problematic string. I found this should be fixed by base64 encode/decode "hackfix" - davidwalsh blog with solution.

[milo]

Could you post here/somewhere contents of the unserialized file? To confirm atomic access issue or serialize/unserialize bug.

[podolinek]

Well, I don't know which file is the problem. It occurs approx. once a month and tracy log only notice row to error file without any other data.

[milo]

And how do you solve the issue? Deleting some file? Or not?

Btw, I don't think that mentioned blog solution is right. IMHO, they have some DB store/fetch issue and base64() only hides that bug.

[podolinek]

Every time "solved" by removing log file. When remove content of temp directory, no notice on problematic page created. Notice is created in random future time. Anyway, I just modified FileStorage in vendor for log variable $data on problematic page and when notice will be occurred, I will post it here. Hope it will be complete copyable content.

[martinbohmcz]

I am not sure if this is related, but it seems similar. The same error ("Error at offset X of Y bytes") from FileStorage.php:308 occasionally appeared in my logs.

I asked Claude to look into it and it suggested the following:

The problem might be related specifically to files starting with an underscore (_).

FileStorage GC scans directories recursively and treats files whose basename matches "*" as cache entries. The issue is that other parts of Nette (e.g. Latte) can create files that also start with "" — especially lock files for templates whose names begin with "_".

These files are not serialized cache records, but GC still tries to read and unserialize() them, which results in errors like “unserialize(): Error at offset …”. Deleting the cache directory fixes the issue because the foreign _*.lock file disappears.

In my case I had a template located at _includes/some-template.latte (name fictional), which produced files _includes-some-template.php and _includes-some-template.php.lock.

Claude continued:

The contents of the .lock file started with 0942e7. That is not serialized data, but it looks valid enough for unserialize(). In PHP 8, 0942e7 is interpreted as a float in scientific notation (942e7), so unserialize() assumes a serialized numeric value and then fails with “Error at offset X of Y bytes”, because the file is much shorter than expected.

So the error was not caused by corrupted cache data, but by GC attempting to unserialize() a file that was never a serialized cache entry in the first place.

I have renamed _includes to a name without the leading underscore and will monitor whether the problem disappears.

[martinbohmcz]

Just letting you know that it hasn’t happened over the weekend, so the underscore might indeed have been the real cause. @dg

[OndraDol]

I'd like to take a stab at this. Based on @martinbohmcz's excellent diagnosis in the recent comments, the root cause is now clear:

Analysis:

The readMetaAndLock() method calls unserialize() on raw file contents without any error handling. When clean() iterates files matching _*, it picks up non-cache files (e.g., Latte lock files like _template.php.lock) and attempts to deserialize them. The 6-byte header read produces a non-zero $size from garbage content (e.g., "0942e7" → (int) 94207), and the subsequent unserialize() fails with "Error at offset".

Proposed fix:

1. Harden readMetaAndLock() — Replace the unguarded unserialize() + assert(is_array()) with @unserialize() + is_array() runtime validation. Non-cache files will silently return null instead of crashing.

2. Harden readData() — Add defensive @unserialize() for corrupted serialized data (e.g., truncated writes from process crashes).

3. Comprehensive tests — GC with foreign files in cache directory, reading corrupted cache files, and enhanced stress test scenarios.

What this does NOT change:

The write path and locking model remain untouched. The current header-last write strategy (null bytes → data → seek → header) is a deliberate design that uses the header as a commit marker — I see no reason to change it. True atomic writes via temp file + rename would require rethinking the stampede prevention locking model (currently file-handle based), which is a larger effort and a separate concern.

Does this direction make sense?