thephpleague/flysystem · error · UnableToProvideChecksum

Unable to get checksum for $path: $reason

Error message

Unable to get checksum for $path: $reason

What it means

The CalculateChecksumFromStream trait (used by Filesystem itself, PathPrefixedAdapter, and ReadOnlyFilesystemAdapter) computes checksums by opening a read stream and hashing it. Any FilesystemException raised by readStream() — most commonly UnableToReadFile because the path does not exist or is not readable — is wrapped as UnableToProvideChecksum with message 'Unable to get checksum for $path: $reason'. This is the fallback checksum path used when the adapter does not implement ChecksumProvider or rejected the requested algorithm.

Source

Thrown at src/CalculateChecksumFromStream.php:22

namespace League\Flysystem;

use function hash_final;
use function hash_init;
use function hash_update_stream;

trait CalculateChecksumFromStream
{
    private function calculateChecksumFromStream(string $path, Config $config): string
    {
        try {
            $stream = $this->readStream($path);
            $algo = (string) $config->get('checksum_algo', 'md5');
            $context = hash_init($algo);
            hash_update_stream($context, $stream);

            return hash_final($context);
        } catch (FilesystemException $exception) {
            throw new UnableToProvideChecksum($exception->getMessage(), $path, $exception);
        }
    }

    /**
     * @return resource
     */
    abstract public function readStream(string $path);
}

View on GitHub (pinned to b277b5dc3d)

Solutions

  1. Call $filesystem->fileExists($path) first and handle missing files explicitly.
  2. Inspect $e->getPrevious() — it is the original FilesystemException (usually UnableToReadFile) whose reason pinpoints the miss.
  3. Fix the path/prefix or write the file before checksumming.
  4. For adapters that can provide checksums natively, make sure the real adapter (not a decorator stripping the interface) handles ChecksumProvider so you get clearer, metadata-based errors.

Example fix

// before
$fs = new Filesystem(new InMemoryFilesystemAdapter());
$fs->checksum('file.txt'); // nothing written -> UnableToProvideChecksum

// after
if ($fs->fileExists('file.txt')) {
    $checksum = $fs->checksum('file.txt');
} else {
    // write first or report missing file
}
Defensive patterns

Strategy: try-catch

Validate before calling

if ( ! $filesystem->fileExists($path)) {
    throw new DomainException("Cannot checksum missing file: {$path}");
}
// Also guard the algorithm name: only FilesystemException is caught in the trait,
// so an unknown algo (hash_init ValueError) escapes uncaught.
if ( ! in_array($algo, hash_algos(), true)) {
    throw new InvalidArgumentException("Unknown hash algorithm: {$algo}");
}

Try / catch

use League\Flysystem\UnableToProvideChecksum;

try {
    $checksum = $filesystem->checksum($path, ['checksum_algo' => $algo]);
} catch (UnableToProvideChecksum $e) {
    $previous = $e->getPrevious(); // original FilesystemException, usually UnableToReadFile
    if ($previous instanceof League\Flysystem\UnableToReadFile) {
        // file missing or unreadable: recover explicitly
        return $regenerateArtifact($path);
    }
    throw $e;
}

Prevention

When it happens

Trigger: $filesystem->checksum($path) on an adapter without native checksum support (InMemory, Zip, WebDAV via decorators, PathPrefixedAdapter wrapping such adapters) when the file is missing; also when Filesystem::checksum() fell back to stream hashing after ChecksumAlgoIsNotSupported and the file cannot be read.

Common situations: Verifying an artifact that was never written or was already consumed/deleted; read-only filesystem wrappers over sparse data; path prefix bugs in PathPrefixedAdapter making every read miss.

Related errors

AI-assisted analysis of thephpleague/flysystem@b277b5dc3d (2026-08-17). Data as JSON: /api/errors/8c9ca273dfa297c9. Report an issue: GitHub.