thephpleague/flysystem · error · UnableToProvideChecksum

Unable to get checksum for $path: $reason

Error message

Unable to get checksum for $path: $reason

What it means

AzureBlobStorageAdapter::checksum() fetches blob properties via fetchMetadata() (Get Blob Properties REST call) and reads the md5_checksum extra field. Any Throwable raised during that fetch is wrapped as UnableToProvideChecksum with the Azure SDK's own message and the original exception chained. This is the generic failure path for Azure checksums.

Source

Thrown at src/AzureBlobStorage/AzureBlobStorageAdapter.php:362

    {
        $location = $this->prefixer->prefixPath($path);

        return $this->client->getBlobUrl($this->container, $location);
    }

    public function checksum(string $path, Config $config): string
    {
        $algo = $config->get('checksum_algo', 'md5');

        if ($algo !== 'md5') {
            throw new ChecksumAlgoIsNotSupported();
        }

        try {
            $metadata = $this->fetchMetadata($this->prefixer->prefixPath($path));
            $checksum = $metadata->extraMetadata()['md5_checksum'] ?? '__not_specified';
        } catch (Throwable $exception) {
            throw new UnableToProvideChecksum($exception->getMessage(), $path, $exception);
        }

        if ($checksum === '__not_specified') {
            throw new UnableToProvideChecksum('No checksum provided in metadata', $path);
        }

        return bin2hex(base64_decode($checksum));
    }

    public function temporaryUrl(string $path, DateTimeInterface $expiresAt, Config $config): string
    {
        if ( ! $this->serviceSettings instanceof StorageServiceSettings) {
            throw UnableToGenerateTemporaryUrl::noGeneratorConfigured(
                $path,
                'The $serviceSettings constructor parameter must be set to generate temporary URLs.',
            );
        }

View on GitHub (pinned to b277b5dc3d)

Solutions

  1. Verify with $filesystem->fileExists($path) before checksumming.
  2. Inspect $e->getPrevious() for the Azure SDK exception (ServiceException with 404/403 codes) and fix the account, container, or token scope.
  3. Regenerate/extend SAS token validity and ensure it grants read (rc/r) on the container.
  4. Catch UnableToProvideChecksum and distinguish by previous-exception code rather than string matching when you need specific handling.

Example fix

// before
$checksum = $filesystem->checksum('backups/latest.bak'); // blob deleted -> wraps 404

// after
try {
    $checksum = $filesystem->checksum('backups/latest.bak');
} catch (UnableToProvideChecksum $e) {
    $previous = $e->getPrevious();
    if ($previous !== null && str_contains($previous->getMessage(), '404')) {
        // blob missing: trigger re-upload instead of failing verification
    } else {
        throw $e;
    }
}
Defensive patterns

Strategy: try-catch

Validate before calling

if ( ! $filesystem->fileExists($path)) {
    throw new DomainException("Blob missing, cannot verify checksum: {$path}");
}

Try / catch

use League\Flysystem\UnableToProvideChecksum;

try {
    $md5 = $filesystem->checksum($path);
} catch (UnableToProvideChecksum $e) {
    $previous = $e->getPrevious(); // Azure SDK exception (often ServiceException)
    $code = null;
    if (method_exists($previous, 'getCode')) {
        $code = $previous->getCode();
    }
    return match (true) {
        $code === 404 => $onMissingBlob($path),
        $code === 403 || $code === 401 => $onAuthFailure($path),
        default => throw $e,
    };
}

Prevention

When it happens

Trigger: Checksumming a blob that does not exist (404), referencing a container name that is wrong or not provisioned, SAS token/shared-key credentials lacking read permission, network/DNS failure to the blob endpoint, or the path resolving to a directory prefix.

Common situations: Case-sensitive container/blob name mistakes; expired SAS tokens in background workers; environments pointing at the wrong storage account; checksum verification racing an upload that hasn't committed yet.

Related errors

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