Laravel queue:restart is not killing workers

Laravel queue:restart is not killing workers

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

Stefan Bogdanescu

Founder & Senior Architect

Laravel Queue:restart Is Not Killing Workers

When deploying a Laravel application via Envoyer to a non-Forge server, you typically rely on Supervisor to manage long-running processes like queue workers. A common setup involves defining a command in your supervisord.conf that executes php artisan queue:work. During deployment, the standard procedure is to run php artisan queue:restart within the Envoyer hook to signal those workers to shut down gracefully before pulling down new code and restarting Supervisor.

However, in scenarios where this graceful shutdown fails, old processes persist alongside new ones, leading to runtime errors as the stale workers execute jobs against outdated application logic. If you find yourself stuck with zombie processes that refuse to die despite running queue:restart, the issue often lies not in Laravel's logic but in how Supervisor handles process groups and signals.

Why queue:restart Appears to Do Nothing

The php artisan queue:work --stop command (invoked by the restart Artisan command) sends a termination signal to the PHP process running the worker. Under normal circumstances, Laravel catches this signal and exits cleanly. When you run php artisan queue:restart, it essentially runs queue:work --stop in the current shell, broadcasts the signal, and waits for the processes to exit before exiting itself.

If the processes remain active after this command, two primary factors are usually at play:

  1. Supervisor Blocking the Signal: Supervisor manages its child processes separately from your terminal session. If Supervisor is configured to send SIGHUP or other signals to restart workers without killing them first, it might be interfering with the manual kill signal sent by Laravel.
  2. Process Group Mismatch: When you run queue:restart manually from a specific user's shell (e.g., data), the command targets processes running under that session. However, if Supervisor spawned those workers in a detached process group or if they are owned by a different user, the signal might not propagate as expected depending on your system's permission settings and how the signal was forwarded.

In the scenario described, the ps -aux output shows multiple processes (PIDs 4347–4384) all running with identical memory profiles and timestamps, suggesting they are indeed old instances that have not received a fatal termination signal. The fact that killing these manually allows Supervisor to spawn new ones correctly confirms that the worker application itself is fine; the problem is strictly in the lifecycle management of the existing processes.

Diagnosing the Process Group Issue

To understand why the manual kill isn't working, you need to inspect the process group IDs. Run the following command to see more details about the running workers:

ps -ef --forest | grep queue:work

Or, for a deeper dive into signal handling:

ps -o pid,ppid,pgid,user,args -p <PID>

If you notice that the PIDs shown in ps do not match the ones Supervisor is tracking, or if the processes are running under a different user than expected, this could explain the disconnect.

The Solution: Explicitly Killing Before Restarting

The most reliable fix when queue:restart fails to terminate workers is to bypass the graceful handshake and explicitly kill the Supervisor-managed children before restarting the service. This ensures that no stale code runs against your new deployment.

You can achieve this by directly interacting with Supervisor from the Envoyer hook or via a script. Instead of relying solely on the Artisan command, update your deployment hook to force-kill the workers first:

# Stop Supervisor children explicitly
sudo supervisorctl stop queue-worker:*

# Wait briefly for processes to clear
sleep 2

# Restart Supervisor to spin up new workers with fresh code
sudo supervisorctl reread
sudo supervisorctl update

Alternatively, if you prefer a one-liner approach within your Envoyer hook:

cd ~/app/current
sudo supervisorctl stop queue-worker:*
php artisan optimize:clear # Optional but recommended after deployment
sudo supervisorctl start queue-worker:*

This approach guarantees that the old PHP processes are terminated immediately by Supervisor, regardless of whether they are listening for a specific signal from the Artisan command. Once Supervisor has fully restarted, it will spawn new worker instances using the updated application code, resolving the conflict between old and new versions.

Trade-offs and Best Practices

While forcing a kill is effective, it does introduce a brief window where no jobs are being processed. To minimize downtime, consider increasing the stopwaitsecs setting in your Supervisor configuration if you want to allow Laravel's graceful shutdown logic more time before Supervisor forces an exit. However, for critical deployments where code consistency is paramount, the explicit stop-and-start sequence remains the safest pattern.

Ensure that your Envoyer hook includes a step to clear caches and optimize after the restart, as stale cache files can also cause issues if they weren't invalidated during the deployment. By combining explicit process management with standard Laravel maintenance tasks, you create a robust deployment pipeline that prevents zombie workers from causing production incidents.

Our network