Last updated on 4th June 2026

Cleaning up a corrupted shared directory

If a previous zero-downtime deployment failed partway through, it can leave stray entries inside your server's shared/ directory. Every subsequent deployment then fails at the Linking files from shared path to release step, because DeployHQ walks shared/ to create symlinks into each new release and walks into the corruption.

You will see one of the following in your deployment log:

Failed to create symlink ... Output: ln: failed to create symbolic link ...: No such file or directory

or, on older versions of DeployHQ, simply:

Something went wrong during the deployment

A telltale sign is that the failing path is unusually long and contains pieces of your server's absolute path, for example: releases/<timestamp>/storage/app/app/var/www/.../shared/storage/app/app. That nested-path-inside-itself shape comes from the symlinker recursing through a self-referential entry inside shared/.

Diagnose

SSH into the affected server and look inside the shared directory mentioned in the failing path. For a Laravel project, that is usually shared/storage/:

ls -la /path/to/site/shared/storage/app/

If you see a subdirectory that does not belong (for example, an app/ inside storage/app/, or any directory whose name is a piece of your absolute server path), shared/ is corrupted and needs cleaning up.

Fix

Back up the corrupted tree so you can inspect it later, then recreate the directories your application expects.

For a Laravel project:

cd /path/to/site/shared

mv storage storage.broken-$(date +%F)

mkdir -p storage/app/public \
         storage/app/private \
         storage/framework/cache \
         storage/framework/sessions \
         storage/framework/views \
         storage/logs

chown -R web-user:web-group storage

Replace web-user:web-group with whatever user and group your web application runs as.

If shared/bootstrap/cache/ is also affected:

mv bootstrap bootstrap.broken-$(date +%F)
mkdir -p bootstrap/cache
chown -R web-user:web-group bootstrap

Then trigger a new deployment. The shared symlink step should complete cleanly, and any post-deploy SSH commands will then run as configured.

Prevent it from happening again

  1. Add your runtime directories to Excluded Files in your project so they are never re-uploaded with the rest of your repository. For Laravel:
  • storage
  • storage/**
  • bootstrap/cache
  • bootstrap/cache/**

  1. Add the same directories under your server's atomic deployment settings as Shared Directories, so DeployHQ creates and maintains the symlinks consistently.

  2. Any post-deploy SSH command that creates files or symlinks (for example, php artisan storage:link) must change into the release path first:

   cd $RELEASE_PATH && php artisan storage:link

Running these commands without the cd will create files or symlinks in the wrong working directory, which is the most common way shared/ gets corrupted in the first place.