[Bug]: Default PHP socket (herd.sock) not created on macOS, causing 502 Bad Gateway

[memorasolutions]

Environment

• Herd Version: 1.24.2
• Operating System: macOS Sequoia 15 (Darwin 25.0.0)
• PHP Versions Installed: 8.2, 8.3, 8.4, 8.5
• Architecture: Apple Silicon (ARM64)

Description

After restarting Herd, all sites return 502 Bad Gateway or ERR_CONNECTION_REFUSED. Nginx starts correctly but cannot communicate with PHP-FPM.

Root Cause

The default PHP socket herd.sock is not created, while version-specific sockets exist:

• ✅ herd82.sock
• ✅ herd83.sock
• ✅ herd84.sock
• ❌ herd.sock (missing)

Nginx configuration references herd.sock for sites without isolated PHP versions, causing the 502 error:

connect() to unix:/Users/.../Herd/herd.sock failed (2: No such file or directory)

Workaround

Creating a symlink resolves the issue temporarily:

ln -sf ~/Library/Application\ Support/Herd/herd84.sock ~/Library/Application\ Support/Herd/herd.sock
herd restart

Expected Behavior

Herd should automatically create herd.sock pointing to the default PHP version, or nginx configs should reference the versioned socket directly.

Additional Context

A secondary issue was discovered: a deleted site (___CRÉATION_DEVIS___.test) had orphaned SSL config files (.conf, .key) but the certificate (.crt) was missing. This prevented nginx from starting entirely with the error:

cannot load certificate "...___CRÉATION_DEVIS___.test.crt": No such file or directory

Removing the orphaned files from ~/Library/Application Support/Herd/config/valet/Certificates/ and Nginx/ allowed nginx to start.

Suggested Fix

1. Ensure herd.sock symlink is created/updated when PHP default version changes
2. Clean up orphaned SSL/nginx configs when a site is removed or unlinked

---

Reported by: Stéphane Lapointe (stephane@memora.ca)

[memorasolutions]

Complete Temporary Fix

For anyone experiencing this issue, here are all the steps to resolve it:

Step 1: Kill all Herd processes

sudo killall nginx
sudo killall php-fpm
sudo killall dnsmasq
pkill -f "Herd"

Step 2: Check if port 80 is blocked

sudo lsof -i :80

If something is using port 80, kill that process first.

Step 3: Clean up old PID and socket files

rm -f ~/Library/Application\ Support/Herd/.pid/*.pid
rm -f ~/Library/Application\ Support/Herd/*.sock

Step 4: Check nginx logs for SSL certificate errors

herd log nginx --lines=50

If you see errors like cannot load certificate "site_name.test.crt": No such file or directory, remove the orphaned config files:

rm -f ~/Library/Application\ Support/Herd/config/valet/Certificates/site_name.test.*
rm -f ~/Library/Application\ Support/Herd/config/valet/Nginx/site_name.test

Step 5: Restart Herd

open -a Herd
# or
herd restart

Step 6: Create the missing default socket symlink

# Check which sockets exist
ls ~/Library/Application\ Support/Herd/*.sock

# Create symlink to your default PHP version (e.g., PHP 8.4)
ln -sf ~/Library/Application\ Support/Herd/herd84.sock ~/Library/Application\ Support/Herd/herd.sock

Step 7: Verify nginx is running

pgrep -l nginx

Your sites should now be accessible.