Supervisord troubleshooting

Program in FATAL or BACKOFF state

The process exited too quickly or failed to start. Check supervisorctl tail myapp stderr and the program's log file. Run the command= manually as the configured user= to reproduce the error outside supervisord.

Restart loop (spawn error)

Supervisord keeps restarting a crashing process. Fix the underlying command failure first. Set autorestart=unexpected so clean exits (code 0) are not restarted. Temporarily use autorestart=false while debugging.

unix:///var/run/supervisor.sock no such file

The supervisord daemon is not running, or the socket path in supervisorctl config does not match supervisord.conf. Start the daemon: systemctl start supervisor or supervisord -c /etc/supervisor/supervisord.conf.

Config changes not applied

Editing files is not enough — run supervisorctl reread to load changes, then supervisorctl update to add/remove/restart affected programs. A full daemon restart is rarely needed.

Permission denied on logs or socket

Ensure stdout_logfile= paths exist and are writable by the program's user=. The unix socket directory must allow the supervisord user and anyone running supervisorctl to connect.

Program works manually but not under supervisord

Supervisord does not load shell profiles. Set environment= and use absolute paths in command=. Set directory= if the app expects a specific working directory.

Debugging workflow

1. Check daemon and program status

2. Read program logs

3. Run command manually

Migrating to systemd

When retiring supervisord on a modern host, translate each [program:x] to a .service unit. See the systemd lab for unit file format, logging with journalctl, and enable-at-boot with systemctl enable.