What causes "Path must not be an empty string" in Intervention/image?

Guard for the empty string before calling save() and fail with your own clear error

Intervention/image · error · InvalidArgumentException

Path must not be an empty string

Error message

Path must not be an empty string

What it means

File::save() refuses an empty target path with InvalidArgumentException before touching the filesystem. You reach this through the EncodedImage/File API - $image->encode(...)->save('') - because the higher-level Image::save() has its own identical guard and would throw earlier. It almost always means a path variable that was assembled from missing input collapsed to an empty string.

Source

Thrown at src/File.php:75

        }

        return new self($stream);
    }

    /**
     * {@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(

View on GitHub (pinned to 5598b9e397)

Solutions

Guard for the empty string before calling save() and fail with your own clear error
Provide a default output path when the dynamic part is missing
Validate path inputs at the application boundary (required, min length)

Example fix

// before
$encoded->save($config->get('output_path') ?? ''); // '' when unset

// after
$path = $config->get('output_path');
if ($path === null || $path === '') {
    throw new RuntimeException('Output path is not configured');
}
$encoded->save($path);

Defensive patterns

Strategy: validation

Validate before calling

if ($path === '') {
    throw new InvalidArgumentException('Output path must not be empty');
}
$encoded->save($path);

Type guard

function isNonEmptyPath(mixed $path): bool
{
    return is_string($path) && $path !== '';
}

Prevention

Validate path inputs as required at the request boundary
Never coalesce missing config to '' when building output paths
Fail with your own descriptive error before calling save()

When it happens

Trigger: Calling $encodedImage->save($path) where $path is '' - e.g. a config key that returned null and was cast to string, or a request parameter that was present but empty.

Common situations: Optional request/config path inputs not validated for emptiness; string concatenation where every part was empty; code paths where the filename variable was never set before use.

Related errors

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