Intervention/image · error · InvalidArgumentException

Path is longer than the configured max. value of " …

Error message

Path is longer than the configured max. value of " . PHP_MAXPATHLEN

What it means

File::save() checks strlen($path) against PHP_MAXPATHLEN (a platform constant: 4096 on most Linux builds) and throws InvalidArgumentException when the target path exceeds it. This mirrors the OS limit, since file operations with longer paths would fail anyway.

Solutions

Shorten the filename: keep a single hash or ID instead of stacked identifiers
Check strlen($path) <= PHP_MAXPATHLEN before calling save() and truncate or reject
Move long metadata into a database and use short keys as filenames

Example fix

// before
$name = implode('-', [$post->slug, $uuid, $hash, time()]) . '.jpg'; // can exceed 4096
$image->save($dir . '/' . $name);

// after
$name = hash('sha256', $post->slug . $uuid) . '.jpg'; // fixed 64 chars + ext
$image->save($dir . '/' . $name);

Defensive patterns

Strategy: validation

Validate before calling

if (strlen($path) > PHP_MAXPATHLEN) {
    throw new InvalidArgumentException('Path exceeds PHP_MAXPATHLEN');
}
$encoded->save($path);

Type guard

function isPathWithinLimit(string $path): bool
{
    return strlen($path) <= PHP_MAXPATHLEN;
}

Prevention

Prefer short hash-based filenames over stacked identifiers
Keep long metadata in a database, not in filenames
Bound generated filename length in your path-builder utility

When it happens

Trigger: Building save paths that stack directories, slugs, UUIDs, timestamps and hashes until they exceed PHP_MAXPATHLEN; embedding very long identifiers (or accidentally a base64 blob) in the filename; deep directory nesting.

Common situations: Generated filenames derived from user titles or composite keys; content-addressed storage appending multiple hashes; accidentally concatenating file contents or URLs into the filename variable.

Related errors

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/222851430757d27b. Report an issue: GitHub.

Appendix: source

Thrown at src/File.php:79

    /**
     * {@inheritdoc}
     *
     * @see FileInterface::save()
     *
     * @throws InvalidArgumentException
     * @throws DirectoryNotFoundException
     * @throws FileNotWritableException
     * @throws StreamException
     */
    public function save(string $path): void
    {
        if ($path === '') {
            throw new InvalidArgumentException('Path must not be an empty string');
        }

        if (strlen($path) > PHP_MAXPATHLEN) {
            throw new InvalidArgumentException(
                "Path is longer than the configured max. value of " . PHP_MAXPATHLEN,
            );
        }

        $dir = pathinfo($path, PATHINFO_DIRNAME);

        if (!is_dir($dir)) {
            throw new DirectoryNotFoundException(
                'Can\'t write to path. Directory "' . $dir . '" does not exist',
            );
        }

        if (!is_writable($dir)) {
            throw new FileNotWritableException(
                'Can\'t write to path. Directory "' . $dir . '" is not writable',
            );
        }

View on GitHub (pinned to 5598b9e397)