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

Unable to create Intervention\Image\Alignment from "{identif

Error message

Unable to create Intervention\Image\Alignment from "{identifier}"

What it means

Intervention Image throws this FileNotFoundException when you pass an SplFileInfo object to ImageManager::read() (or any API that resolves file paths, e.g. font loading) and the directory stored in the SplFileInfo exists but the basename does not. The check happens in filePathFromSplFileInfoOrFail() via file_exists() on $splFileInfo->getPathname(), after the directory check has already passed. It means the object points at a path that is no longer (or never was) present on disk.

Source

Thrown at src/Alignment.php:124

                'top_left',
                'topleft',
                'left-top',
                'left_top',
                'lefttop' => self::TOP_LEFT,

                'middle',
                'center-center',
                'center_center',
                'centercenter',
                'center-middle',
                'center_middle',
                'centermiddle',
                'middle-center',
                'middle_center',
                'middlecenter' => self::CENTER,

                default => throw new InvalidArgumentException(
                    'Unable to create ' . self::class . ' from "' . $identifier . '"',
                ),
            };
        }

        return $position;
    }

    /**
     * Try to create position from given identifier or return null on failure.
     */
    public static function tryCreate(string|self $identifier): ?self
    {
        try {
            return self::create($identifier);
        } catch (InvalidArgumentException) {
            return null;
        }

View on GitHub (pinned to 5598b9e397)

Solutions

Check file_exists($splFileInfo->getPathname()) before calling read() and fail gracefully with your own error handling
Verify the actual path the object carries: var_dump($splFileInfo->getPathname()) and compare with what is on disk (watch for relative vs absolute paths and cwd differences between CLI and web)
If the file may be moved concurrently, copy it to a private temp location and pass an SplFileInfo for that copy
If the file should exist, re-upload or regenerate it before retrying

Example fix

// before
$image = $manager->read(new SplFileInfo($userPath)); // FileNotFoundException when file is gone

// after
$info = new SplFileInfo($userPath);
if (!file_exists($info->getPathname())) {
    throw new RuntimeException('Uploaded image is no longer available: ' . $info->getPathname());
}
$image = $manager->read($info);

Defensive patterns

Strategy: validation

Validate before calling

$info = $splFileInfo instanceof \SplFileInfo ? new \SplFileInfo($splFileInfo->getPathname()) : $splFileInfo;
if (!$info instanceof \SplFileInfo || !file_exists($info->getPathname())) {
    // reject before ImageManager::read()
    throw new \RuntimeException('Image file not found: ' . ($info ? $info->getPathname() : 'n/a'));
}
$image = $manager->read($info);

Type guard

/** @throws \LogicException when the SplFileInfo target is not an existing regular file */
function assertExistingFile(\SplFileInfo $info): void
{
    if (!file_exists($info->getPathname()) || !$info->isFile()) {
        throw new \LogicException('Not an existing regular file: ' . $info->getPathname());
    }
}

Try / catch

use Intervention\Image\Exceptions\FileNotFoundException;

try {
    $image = $manager->read($file);
} catch (FileNotFoundException $e) {
    // log the exact missing path from the message and report a friendly error
    logger()->warning($e->getMessage());
    abort(404, 'Image not available');
}

Prevention

Treat any user-supplied path as untrusted: resolve it with realpath() against an allowed base directory before wrapping it in SplFileInfo
Process uploads from a private copy you own so other code cannot delete the file mid-request
In UIs that list images, check file existence when listing rather than only when processing

When it happens

Trigger: ImageManager::read(new SplFileInfo('uploads/photo.png')) where 'uploads/' exists but 'photo.png' does not; passing an SplFileInfo built from a stale or misspelled filename; an SplFileInfo captured earlier whose file was deleted or moved by another process (temp upload already moved, queue worker races); passing a relative basename when the object was constructed without the directory.

Common situations: Upload pipelines where the file is renamed/moved between validation and image processing; typos or missing file extensions in paths built from user input; concurrent workers processing the same file; code migrated from passing strings (readableFilePathOrFail) to SplFileInfo objects where the path semantics differ slightly.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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