Systemd service failed to start. Cuatro palabras que arruinan cualquier despliegue. El servicio no arranca, no hay mensaje de error claro y el servidor está en producción. En este post te explico exactamente cómo diagnosticar y solucionar los errores más comunes de Systemd, paso a paso.

Paso 1: Lo primero siempre es systemctl status

Antes de hacer nada, ejecuta esto para ver qué ha pasado:

sudo systemctl status nombre-servicio

El output te da mucha información. Lo más importante está en estas líneas:

● mi-app.service - Mi aplicación Node.js
     Loaded: loaded (/etc/systemd/system/mi-app.service; enabled)
     Active: failed (Result: exit-code)  # ← aquí está el problema
    Process: 1234 ExecStart=/usr/bin/node /home/victor/mi-app/index.js
             (code=exited, status=1/FAILURE)

# Últimas líneas del log:
May 18 06:00:01 servidor node[1234]: Error: Cannot find module './config'

Estado	Qué significa
active (running)	El servicio está corriendo correctamente
failed (exit-code)	El proceso terminó con error
failed (timeout)	El servicio tardó demasiado en arrancar
activating (start)	Intentando arrancar — puede estar colgado
inactive (dead)	Detenido, no ha fallado

Paso 2: Ver los logs completos con journalctl

# Todos los logs del servicio
journalctl -u nombre-servicio

# Logs del último arranque fallido
journalctl -u nombre-servicio -b

# Logs en tiempo real mientras intentas arrancar
journalctl -u nombre-servicio -f &
sudo systemctl start nombre-servicio

# Solo errores
journalctl -u nombre-servicio -p err

# Logs de los últimos 10 minutos
journalctl -u nombre-servicio --since "10 minutes ago"

Busca líneas con ERROR, FATAL, failed, Permission denied o No such file — suelen ser el origen del problema.

Causa 1: El ejecutable no existe o la ruta está mal

# Error típico:
# ExecStart=/usr/bin/node: No such file or directory

# Verificar dónde está el ejecutable
which node
which python3

# Usar la ruta absoluta en el unit file, nunca relativa
ExecStart=/usr/bin/node /home/victor/mi-app/index.js   # ✅ correcto
ExecStart=node index.js                                  # ❌ incorrecto

Causa 2: Problemas de permisos

# Error típico: Permission denied

chmod +x /home/victor/mi-app/inicio.sh
sudo -u victor ls /home/victor/mi-app/

Si tienes dudas sobre permisos, consulta el post sobre chmod, chown y umask en Linux.

Causa 3: Variables de entorno que no carga Systemd

# Systemd no carga .bashrc ni .profile
# Definir variables en el unit file:

[Service]
Environment=DATABASE_URL=postgres://localhost/midb
Environment=NODE_ENV=production

# O desde un archivo:
EnvironmentFile=/etc/mi-app/env

Causa 4: El servicio arranca antes de que esté listo lo que necesita

Si tu app necesita la red, la base de datos u otro servicio, puede fallar porque arranca demasiado pronto. Se soluciona con las directivas After y Requires:

[Unit]
Description=Mi aplicación
After=network-online.target postgresql.service
Wants=network-online.target
Requires=postgresql.service

[Service]
ExecStart=/usr/bin/node /home/victor/mi-app/index.js

Directiva	Qué hace
After=	Arranca después de ese servicio, pero no lo exige
Wants=	Intenta arrancar ese servicio, pero no falla si no puede
Requires=	Exige que ese servicio esté activo — si falla, falla también el tuyo

Causa 5: Timeout — el servicio tarda demasiado en arrancar

[Service]
TimeoutStartSec=120

# O desactivarlo completamente (con precaución)
TimeoutStartSec=infinity

Causa 6: El servicio sale inmediatamente (exit code 0 o 1)

# Probar el comando manualmente
sudo -u victor /usr/bin/node /home/victor/mi-app/index.js

# Para scripts que corren una sola vez:
[Service]
Type=oneshot
RemainAfterExit=yes

Workflow de diagnóstico

1. systemctl status servicio — ver el estado y últimas líneas del log
2. journalctl -u servicio -n 50 — ver los 50 últimos mensajes
3. Ejecutar el ExecStart manualmente con el mismo usuario
4. Verificar que la ruta del ejecutable es correcta: which comando
5. Comprobar permisos del script y directorio de trabajo
6. Verificar variables de entorno en el unit file
7. Comprobar dependencias con After= y Requires=
8. Tras cualquier cambio: systemctl daemon-reload

Conclusión

El 90% de los casos de systemd service failed to start se resuelven con los tres primeros pasos: systemctl status, journalctl y ejecutar el comando manualmente. El log siempre te dice qué ha pasado — solo hay que saber leerlo.

Si aún no has leído el post anterior sobre Systemd para gestionar servicios Linux, empieza por ahí. En el próximo post veremos Networking en Linux: ip, ss y netstat. ¿Qué error de Systemd te ha dado más problemas? Déjalo en los comentarios.