What causes "Error occurred while saving item %s (%s) to cache: %s" in rectorphp/rector?

Clear the Rector cache and re-run: rm -rf .cache/rector (or your configured cache directory / the sys-temp default)

rectorphp/rector · error · CachingException

Error occurred while saving item %s (%s) to cache: %s

Error message

Error occurred while saving item %s (%s) to cache: %s

What it means

FileCacheStorage::save() persists a cache item by var_export()-ing a CacheItem into PHP code; it snapshots error_get_last() before and after and treats any new PHP diagnostic raised during the export as fatal, throwing CachingException with the underlying message. In practice this means PHP could not cleanly export the cached value (e.g. circular references or unexportable internal state).

Source

Thrown at src/Caching/ValueObject/Storage/FileCacheStorage.php:67

            }
            return $cacheItem->getData();
        })($key, $variableKey);
    }
    /**
     * @param mixed $data
     */
    public function save(string $key, string $variableKey, $data): void
    {
        $cacheFilePaths = $this->getCacheFilePaths($key);
        $this->filesystem->mkdir($cacheFilePaths->getFirstDirectory());
        $this->filesystem->mkdir($cacheFilePaths->getSecondDirectory());
        $filePath = $cacheFilePaths->getFilePath();
        $tmpPath = \sprintf('%s/%s.tmp', $this->directory, Random::generate());
        $errorBefore = \error_get_last();
        $exported = @\var_export(new CacheItem($variableKey, $data), \true);
        $errorAfter = \error_get_last();
        if ($errorAfter !== null && $errorBefore !== $errorAfter) {
            throw new CachingException(\sprintf('Error occurred while saving item %s (%s) to cache: %s', $key, $variableKey, $errorAfter['message']));
        }
        // for performance reasons we don't use SmartFileSystem
        FileSystem::write($tmpPath, \sprintf("<?php declare(strict_types = 1);\n\nreturn %s;", $exported), null);
        $copySuccess = @\copy($tmpPath, $filePath);
        @\unlink($tmpPath);
        if ($copySuccess) {
            return;
        }
        if (\DIRECTORY_SEPARATOR === '/' || !\file_exists($filePath)) {
            throw new CachingException(\sprintf('Could not write data to cache file %s.', $filePath));
        }
    }
    public function clean(string $key): void
    {
        $cacheFilePaths = $this->getCacheFilePaths($key);
        $this->processRemoveCacheFilePath($cacheFilePaths);
        $this->processRemoveEmptyDirectory($cacheFilePaths->getSecondDirectory());
        $this->processRemoveEmptyDirectory($cacheFilePaths->getFirstDirectory());

View on GitHub (pinned to 408fcb0ff1)

Solutions

Clear the Rector cache and re-run: rm -rf .cache/rector (or your configured cache directory / the sys-temp default)
If it recurs, identify the item from the key in the message (file path hash) and inspect what the run produces for that file -- run with --debug
Reproduce with the cache disabled/moved to a fresh directory (Option::CACHE_DIR) to confirm it is cache-specific
If a stock rule triggers it consistently, report the rule name, message and stack trace to rectorphp/rector with --debug output

Example fix

# before: poisoned/stale cache makes every run throw
vendor/bin/rector process src

# after: wipe cache and retry
rm -rf .cache/rector
vendor/bin/rector process src

Defensive patterns

Strategy: fallback

Try / catch

catch \Rector\Caching\Exception\CachingException around the run; on save/export failures, delete the cache directory and re-run once from scratch (a poisoned cache is the most common cause). Keep the exception message -- it contains the failing cache key.

Prevention

Clear the cache after Rector or PHP major upgrades (rm -rf .cache/rector)
Treat repeated export errors on the same key as a bug: capture --debug output and report it
Avoid experimental rules that attach non-plain values (resources, closures) to diff/error objects

When it happens

Trigger: A parallel or normal run reaches cache-save with data that triggers a PHP warning during var_export: values with circular references, resources, or malformed data produced by a custom/experimental rule; occasionally a corrupted cache from a crashed previous run.

Common situations: After upgrading Rector or PHP versions with a stale cache directory; running custom rules whose diff/error objects contain unexportable values; disk/memory pressure turning into PHP warnings mid-export.

Related errors

AI-assisted analysis of rectorphp/rector@408fcb0ff1 (2026-08-21). Data as JSON: /api/errors/8257d4c55353c4dc. Report an issue: GitHub.