Saving files locally with Laravel

Saving files locally with Laravel

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why Your Local File Uploads Return 404s in Laravel

When building a file upload endpoint in Laravel, it is easy to mix up the physical storage path with the public URL. A common scenario involves using Storage::disk('public') to write files, storing the filename in the database, and then attempting to serve those files via an API response. If you are returning a 404 error despite having run php artisan storage:link, the issue almost always lies in how the URL is constructed relative to your web server's document root.

The Storage Link Mechanism

The command php artisan storage:link creates a symbolic link from /public/storage to /storage/app/public. This symlink ensures that files saved to the public disk are accessible via a URL path starting with /storage/. However, this setup relies entirely on the web server serving content from the /public directory.

In your implementation, you correctly save the file using:

Storage::disk('public')->put($name, $file);

This places the file at /storage/app/public/{filename}. Physically, this is correct. However, when you retrieve the filename from the database and attempt to generate a URL, the logic must account for the symlink structure.

Constructing the Correct Asset URL

The core issue in your code snippet is the use of asset($asset). The helper function url() or asset() prefixes the path with your application's domain root (e.g., http://127.0.0.1:8000). When you pass just the filename (e.g., 1524042807kdvws.pdf) to this helper, it generates /storage/1524042807kdvws.pdf.

Because of the symlink created by storage:link, this URL corresponds to the physical path /public/storage/1524042807kdvws.pdf. If your web server (like PHP's built-in server or Apache/Nginx configured for Laravel) is correctly pointing its document root to the public folder, this URL should work.

If you are seeing a 404, consider these specific possibilities:

  1. Missing Symlink: Ensure the symlink actually exists and points to the correct location. You can verify this by running ls -la /storage/app/public and comparing it with ls -la public/storage. If the symlink is missing or broken, the web server cannot find the files even if they exist on disk.
  2. Incorrect Document Root: If you are running Laravel outside of a standard framework (e.g., inside Docker or a custom deployment), ensure your Nginx or Apache configuration points to the public directory as the document root. If the server is looking in the root of the project for files, it will not find anything inside /storage/.
  3. Premature JSON Encoding: In your controller logic, you encode the file names into a JSON string immediately: $response->assets = json_encode($files). Later, you decode this and wrap them with asset(). While this works in theory, ensure that the final response sent to the client is a valid JSON object where the asset URLs are strings, not Blade directives. The asset() helper returns a string URL, but if you are rendering a view or mixing contexts incorrectly, it might not resolve as expected.

Best Practices for Asset Management

To avoid these pitfalls in the future, consider storing the full relative path instead of just the filename when saving to the database. This decouples your logic from the storage:link mechanism entirely:

$path = Storage::disk('public')->put($name, $file); // Returns "storage/app/public/..."
$url = "/storage/{$path}"; 
// Store "$url" in the database instead of just "$name"

When returning data to your Vue frontend, ensure you are sending a JSON array of strings containing the full relative paths (e.g., ["/storage/1524042807kdvws.pdf"]). Your frontend can then prepend the base URL or use window.location.origin to construct the absolute URL.

Alternatively, if you prefer keeping just the filename in the database, rely on the asset() helper but ensure your development environment is configured to serve the /storage directory directly. For production environments, it is often safer to configure your web server to explicitly allow access to the /storage directory and avoid relying solely on symlinks, which can sometimes cause permission issues depending on the OS.

Final Verification

Before assuming the code logic is flawed, always inspect the actual HTTP response headers and the file system permissions. Ensure that the user running your PHP process has write permissions for /storage/app/public and that the web server user (e.g., www-data) can read the files there. A 404 error usually indicates a routing or document root mismatch rather than a logic error in the upload handler itself.

Our network