Laravel 8 Jetstream Profile Photos Not Showing: A Deep Dive into Storage Drivers and Configuration
When setting up a new Laravel application with Jetstream, one of the first signs that something is misconfigured is a blank space where the user's profile photo should be. This issue typically manifests when visiting the update-profile-information-form page. The Blade template you are looking at expects an image source derived from $this->user->profile_photo_url. If that URL resolves to nothing, or if the browser cannot fetch the resource, the image fails to render.
The core of this problem usually lies in how Laravel handles file storage and the specific configuration of your filesystems config. In the scenario described, the filesystem is configured with the local driver, pointing to a root directory at storage_path('/public/storage'). While this setup seems correct on paper, it often fails in practice because of a misunderstanding of where Laravel actually places uploaded files versus where you are trying to read them from.
When you upload an avatar using Jetstream's Fortify controller, the file is saved to your disk. However, for the profile_photo_url to work correctly, that file must be accessible via the public URL returned by the storage driver. If your .env file defines APP_URL=http://127.0.0.1:8000 and your config sets the url key to http://127.0.0.1:8000/public/storage/, you must ensure that the public symbolic link exists in your project root.
Many developers encounter this issue because they assume the storage path is automatically exposed. In reality, Laravel serves files from the storage directory only if they are symlinked to public/storage. If you run php artisan storage:link and it already exists but points to an older version or a different mount point, the browser will receive a 404 error when trying to load the profile image.
Another common pitfall involves the visibility of the disk. Your configuration explicitly sets 'visibility' => 'public'. This tells Laravel that files on this disk should be accessible without authentication checks for public URLs. However, if you are running behind a proxy or using a specific server setup where APP_URL does not match the actual origin header sent by browsers, the CDN or proxy might block the request. In local development, this is less common but still a factor if you are accessing the app via an IP address that differs from what is defined in the environment variables.
To diagnose this, inspect the network tab of your browser while viewing the profile page. Look for the failed image request. If you see a 404 error for the path http://127.0.0.1:8000/public/storage/profile_photo_path.jpg, the issue is almost certainly the symbolic link.
If the link is missing, run the following command from your project root:
php artisan storage:link
This creates the necessary symlink so that public/storage points directly to storage/app/public. Once this is done, ensure that the uploaded file actually exists in storage/app/public. The Jetstream controller usually handles moving files from storage/app to storage/app/public automatically, but if you manually moved files or cleared caches, you might need to ensure the destination directory exists:
php artisan storage:link
mkdir -p storage/app/public
There is also a subtle configuration detail regarding the url key in your config/filesystems.php. You defined it as env('APP_URL').'/public/storage/'. This is generally fine, but be aware that if you ever switch to the s3 driver or another remote storage provider, this path will break unless you update the root and url keys accordingly. The trade-off here is convenience versus flexibility; using a relative path like /storage/app/public in your URL logic can sometimes cause issues if the base domain changes, whereas an absolute URL anchored to APP_URL provides consistency across different environments provided the symlink is correct.
If you are deploying this application, remember that the symlink created by storage:link does not travel with your codebase when using deployment tools like Forge or Envoyer. You must run php artisan storage:link on the server after deployment to ensure the photo paths remain valid in production.
Finally, verify that no other disk driver is inadvertently interfering. Ensure your database migration has created the necessary tables for Jetstream's session state and that you haven't accidentally overridden the default file system configuration with a custom provider that points to a non-existent directory. By aligning your storage root, visibility settings, and symbolic links, you can ensure that $this->user->profile_photo_url returns a valid path and the image displays correctly.