What causes "Directory does not exist: $cacheDirectory" in PHPOffice/PhpSpreadsheet?

Create it before enabling: if (!is_dir($dir)) { mkdir($dir, 0775, true); }

PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Writer\Exception

Directory does not exist: $cacheDirectory

Error message

Directory does not exist: $cacheDirectory

What it means

BaseWriter::setUseDiskCaching(bool $useDiskCache, ?string $cacheDirectory = null) enables temporary-disk caching for writers handling large spreadsheets. The directory must already exist: the setter only validates with is_dir() and throws when the path is missing; it never creates the directory for you.

Source

Thrown at src/PhpSpreadsheet/Writer/BaseWriter.php:74

        $this->preCalculateFormulas = $precalculateFormulas;

        return $this;
    }

    public function getUseDiskCaching(): bool
    {
        return $this->useDiskCaching;
    }

    public function setUseDiskCaching(bool $useDiskCache, ?string $cacheDirectory = null): self
    {
        $this->useDiskCaching = $useDiskCache;

        if ($cacheDirectory !== null) {
            if (is_dir($cacheDirectory)) {
                $this->diskCachingDirectory = $cacheDirectory;
            } else {
                throw new Exception("Directory does not exist: $cacheDirectory");
            }
        }

        return $this;
    }

    public function getDiskCachingDirectory(): string
    {
        return $this->diskCachingDirectory;
    }

    protected function processFlags(int $flags): void
    {
        if (((bool) ($flags & self::SAVE_WITH_CHARTS)) === true) {
            $this->setIncludeCharts(true);
        }
        if (((bool) ($flags & self::DISABLE_PRECALCULATE_FORMULAE)) === true) {
            $this->setPreCalculateFormulas(false);

View on GitHub (pinned to 65b080eef4)

Solutions

Create it before enabling: if (!is_dir($dir)) { mkdir($dir, 0775, true); }
Use an absolute path you control, e.g. sys_get_temp_dir() . '/xlsx-cache'.
Verify both is_dir($dir) and is_writable($dir) and surface a clear configuration error otherwise.
Compare the environment variable or mount actually present in the failing environment against local.

Example fix

// before
$writer->setUseDiskCaching(true, '/var/cache/xlsx'); // dir absent -> throws

// after
$dir = '/var/cache/xlsx';
if (!is_dir($dir)) {
    mkdir($dir, 0775, true);
}
$writer->setUseDiskCaching(true, $dir);

Defensive patterns

Strategy: validation

Validate before calling

$dir = rtrim((string) (getenv('XLSX_CACHE_DIR') ?: sys_get_temp_dir() . '/xlsx-cache'), '/');
if (!is_dir($dir)) {
    mkdir($dir, 0775, true);
}
if (!is_writable($dir)) {
    throw new RuntimeException('Cache directory not writable: ' . $dir);
}
$writer->setUseDiskCaching(true, $dir);

Try / catch

use PhpOffice\PhpSpreadsheet\Writer\Exception as WriterException;

try {
    $writer->setUseDiskCaching(true, $dir);
} catch (WriterException $e) {
    // disk path unusable: continue with in-memory caching
    $writer->setUseDiskCaching(false);
}

Prevention

Provision cache directories in deployment (image build, entrypoint), not at request time.
Always pair the two checks: is_dir() and is_writable().
Use absolute paths sourced from one configuration point so CLI and web SAPI agree.

When it happens

Trigger: setUseDiskCaching(true, '/var/cache/xlsx') when that path does not exist; a relative path like 'cache/xlsx' resolved against a different working directory (web SAPI vs CLI); an env-configured path that is empty, misspelled, or points to an unmounted volume.

Common situations: Deployments where the cache directory is not part of the image; Docker/Kubernetes volumes not mounted at the expected path; CI environments lacking the app's tmp directory; paths that work locally but differ on the server.

Related errors

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/1aed3092c2f4ed5f. Report an issue: GitHub.