What causes "Argument $path must not be an empty string" in Intervention/image?

Pass null (not '') when you want to save back to the original file path

Intervention/image · error · Intervention\Image\Exceptions\InvalidArgumentException

Argument $path must not be an empty string

Error message

Argument $path must not be an empty string

What it means

Image::save() treats an empty string as an explicitly invalid path, distinct from null. Passing null means 'reuse the original file path from the image origin', while '' is almost certainly a bug — typically an unset variable or missing user input coerced to a string. The check runs before any encoding work, so nothing is written when it throws.

Source

Thrown at src/Image.php:309

        return $this->driver()->specializeAnalyzer($analyzer)->analyze($this);
    }

    /**
     * {@inheritdoc}
     *
     * @see ImageInterface::save()
     *
     * @throws InvalidArgumentException
     * @throws EncoderException
     * @throws DirectoryNotFoundException
     * @throws FileNotWritableException
     * @throws StreamException
     * @throws NotSupportedException
     */
    public function save(?string $path = null, mixed ...$options): ImageInterface
    {
        if ($path === '') {
            throw new InvalidArgumentException('Argument $path must not be an empty string');
        }

        if (is_null($path) && is_null($this->origin()->filePath())) {
            throw new EncoderException('Unable to determine path for saving');
        }

        $path = is_null($path) ? $this->origin()->filePath() : $path;

        try {
            // try to determine encoding format by file extension of the path
            $encoded = $this->encode(new FilePathEncoder($path, ...$options));
        } catch (EncoderException) {
            // fallback to encoding format by media type
            $encoded = $this->encode(new MediaTypeEncoder(null, ...$options));
        }

        $encoded->save($path);

View on GitHub (pinned to 5598b9e397)

Solutions

Pass null (not '') when you want to save back to the original file path
Default missing user input to null: $request->input('path') returns null when absent — avoid ?? '' overrides
Validate: if ($path === '') { abort / use fallback path } before calling save()
Initialize path variables to null rather than '' so the origin-fallback logic can work

Example fix

// before
$path = $request->input('path') ?? '';
$image->save($path); // throws when input missing

// after
$path = $request->input('path'); // null when absent
$image->save($path); // falls back to original file path

Defensive patterns

Strategy: validation

Validate before calling

$path = $request->input('path'); // null, not ''
if ($path === '') {
    $path = null; // let save() fall back to the origin path
}
$image->save($path);

Type guard

function isSaveablePath(?string $path): bool
{
    return $path === null || $path !== '';
}

Try / catch

try {
    $image->save($path);
} catch (InvalidArgumentException $e) {
    // empty-string bug in caller: fix the caller, do not retry
}

Prevention

Default path variables to null, never ''
Avoid ?? '' overrides on request/config lookups feeding save()
Add a save-path unit assertion in controller tests

When it happens

Trigger: $image->save('') — e.g. save($request->input('path')), save($config['output'] ?? '') or save($filename) where $filename was initialized to '' and never set. Note save(null) is valid when the image has a file origin.

Common situations: Form/config values defaulting to empty string instead of null, path variables reset in loops, or string interpolation producing '' — common in Laravel controller code feeding request input straight to save().

Related errors

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