Class 'League\Flysystem\AwsS3v3\AwsS3Adapter' not found (Laravel + Heroku)
You are running into a classic discrepancy between local development and production environments. On your local machine, everything works perfectly: you upload an image via your dashboard, and it lands in the AWS S3 bucket without issue. However, as soon as you deploy to Heroku, the application fails with a Class 'League\Flysystem\AwsS3v3\AwsS3Adapter' not found error.
This specific exception message indicates that PHP cannot locate the class definition for the AWS S3 adapter within your application's namespace at runtime. Since you have already attempted to remove and reinstall the package via Composer on both environments without success, the problem likely isn't the presence of the package itself, but rather how or when it is being loaded, or a missing dependency that manifests differently in containerized environments compared to local setups.
The Flysystem Version Mismatch
The error explicitly names AwsS3Adapter, which belongs to the namespace League\Flysystem\AwsS3v3. This naming convention suggests you are using Flysystem version 2.x or an older iteration of the AWS SDK v3 integration. In recent years, the ecosystem has shifted significantly. The legacy AwsS3v1 adapter is being deprecated in favor of AwsS3v3, which relies on the newer Amazon SDK for PHP V3 (aws/aws-sdk-php).
If your local environment has a specific version of league/flysystem-aws-s3-v2 or league/flysystem-aws-s3-v3 installed, but your Heroku dyno loads a different set of dependencies due to cache issues or conflicting require statements in composer.json, you might be hitting a namespace collision. The most robust solution is to ensure strict version alignment.
Check your composer.json file. You should explicitly require the correct package for the adapter you intend to use. If you are aiming for the modern SDK v3 approach, ensure you have:
"require": {
"league/flysystem-aws-s3-v3": "^3.0",
"aws/aws-sdk-php": "^3.0"
}
However, if you are currently using Flysystem v2 (which is still widely supported), the correct package is league/flysystem-aws-s3-v2. Attempting to use an adapter from the wrong version will result in exactly the "Class not found" error you are seeing.
Heroku Composer and Cache Issues
Heroku runs on a shared container environment, which means it does not cache Composer packages indefinitely like your local machine might. When you deploy, Heroku executes composer install (or composer update) fresh on every build.
Sometimes, even after running composer dump-autoload, the autoloader generated for one environment can conflict with another if configuration files have changed. Ensure that your composer.lock file is committed to your repository. Without a lock file, Heroku will attempt to satisfy version constraints from scratch, potentially pulling in incompatible versions of dependencies like guzzlehttp/guzzle, which often acts as the underlying transport layer for AWS interactions.
Run these commands locally after updating your requirements to verify consistency:
composer update league/flysystem-aws-s3-v2
vendor/bin/phpstan analyse src/ # Optional static analysis check
Then, push the changes to Heroku. It is crucial that you commit both composer.json and composer.lock. If you omit the lock file, Heroku might resolve dependencies differently than your local environment, leading to the adapter class being missing in production while existing locally.
Environment Variable Configuration
Another frequent cause of this error in production environments like Heroku involves configuration loading order. The AWS SDK and Flysystem often rely on environment variables defined in .env files to initialize credentials. If the AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY are missing, or if the AWS_DEFAULT_REGION is unset, the adapter initialization might fail silently or throw a class not found error depending on how the factory pattern is implemented in your service provider.
Ensure your .env file contains valid credentials before deploying to Heroku. While local testing often uses mock credentials or localstack, production requires actual IAM permissions. The AWS S3 adapter will attempt to instantiate immediately upon loading; if the underlying Guzzle client fails to initialize due to missing auth headers, it can sometimes mask as a class loading error depending on your exception handling strategy.
Finally, verify that your service provider in config/app.php is actually registering the Flysystem disk correctly. If you are using the filesystem facade, ensure the disk name matches exactly what you define in your configuration array:
'filesystems' => [
'default' => 'local', // Or 's3' if that's your default
],
By aligning your Composer versions, committing your lock file, and ensuring environment variables are set correctly on Heroku, the AwsS3Adapter class will load as expected in your production environment.