thephpleague/flysystem · error · UnableToProvideChecksum

Unable to get checksum for $path: $reason

Error message

Unable to get checksum for $path: $reason

What it means

GoogleCloudStorageAdapter::checksum() fetches the object's metadata ($this->bucket->object($path)->info()) and reads the field matching the algorithm (md5Hash, crc32c, or etag). Two failure modes land in the same catch: the Google API call itself fails (404 for missing object, auth, network), or the info array lacks the header, raising LogicException('Header not present: ...'). Both are wrapped as UnableToProvideChecksum with the underlying message.

Source

Thrown at src/GoogleCloudStorage/GoogleCloudStorageAdapter.php:392

        }
    }

    public function checksum(string $path, Config $config): string
    {
        $algo = $config->get('checksum_algo', 'md5');
        $header = static::$algoToInfoMap[$algo] ?? null;

        if ($header === null) {
            throw new ChecksumAlgoIsNotSupported();
        }

        $prefixedPath = $this->prefixer->prefixPath($path);

        try {
            $checksum = $this->bucket->object($prefixedPath)->info()[$header]
                ?? throw new LogicException("Header not present: $header");
        } catch (Throwable $exception) {
            throw new UnableToProvideChecksum($exception->getMessage(), $path);
        }

        return bin2hex(base64_decode($checksum));
    }

    public function temporaryUrl(string $path, DateTimeInterface $expiresAt, Config $config): string
    {
        $location = $this->prefixer->prefixPath($path);

        try {
            return $this->bucket->object($location)->signedUrl($expiresAt, $config->get('gcp_signing_options', []));
        } catch (Throwable $exception) {
            throw UnableToGenerateTemporaryUrl::dueToError($path, $exception);
        }
    }
}

View on GitHub (pinned to b277b5dc3d)

Solutions

  1. Confirm the object exists with fileExists() and inspect the wrapped message for 'Header not present: md5Hash' vs an API 404.
  2. For composite objects, request 'crc32c' instead of 'md5'.
  3. Grant the service account roles/storage.objectViewer (and storage.objects.get) on the bucket.
  4. Catch UnableToProvideChecksum and branch on the message/previous exception to retry transient API failures.

Example fix

// before
$checksum = $adapter->checksum('composed/merged.dat', new Config(['checksum_algo' => 'md5'])); // composite object -> 'Header not present: md5Hash'

// after
$checksum = $adapter->checksum('composed/merged.dat', new Config(['checksum_algo' => 'crc32c'])); // defined for composites
Defensive patterns

Strategy: try-catch

Validate before calling

if ( ! $filesystem->fileExists($path)) {
    throw new DomainException("Object missing, cannot checksum: {$path}");
}
// Composite objects lack md5Hash — request crc32c for anything under a compose() prefix
$algo = str_starts_with($path, 'composed/') ? 'crc32c' : 'md5';

Try / catch

use League\Flysystem\UnableToProvideChecksum;

try {
    $checksum = $filesystem->checksum($path, ['checksum_algo' => 'md5']);
} catch (UnableToProvideChecksum $e) {
    if (str_contains($e->getMessage(), 'Header not present: md5Hash')) {
        // composite object: crc32c is always defined
        return $filesystem->checksum($path, ['checksum_algo' => 'crc32c']);
    }
    // otherwise: 404/auth/network — inspect and handle accordingly
    throw $e;
}

Prevention

When it happens

Trigger: Checksumming a nonexistent object (storage.objects.get returns 404); service-account credentials without storage.objects.get on the bucket; requesting 'md5' on a composite object, whose md5Hash is absent (only crc32c is defined for composites); transient API errors.

Common situations: Composite objects created by gsutil compose or GCS compose() calls; path/prefix mistakes through PathPrefixedAdapter; IAM roles missing object reader; verifying objects right after upload with eventual metadata visibility.

Related errors

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