Depurando serviços systemd que falham com "Failed to start"

2026-06-05 Tempo de leitura: Cerca de 12 min Dificuldade: Intermediário

O que você vai aprender

• Por que systemctl start falha com Failed to start e como isolar a causa
• Onde procurar em status e journalctl
• Os culpados usuais: exit codes, o caminho do ExecStart, permissões, dependências e start-limit

Por onde começar a procurar?

Conclusão: Comece com systemctl status <servico>. O estado Active:, o exit code do Main PID e as últimas ~10 linhas de log geralmente apontam para a causa. Se mostra failed ou activating (auto-restart), o caminho se divide.

$ systemctl status myapp

x myapp.service - My Application
     Loaded: loaded (/etc/systemd/system/myapp.service; enabled; preset: enabled)
     Active: failed (Result: exit-code) since Fri 2026-06-05 10:00:01 UTC; 5s ago
   Main PID: 12345 (code=exited, status=203/EXEC)
        CPU: 4ms

Jun 05 10:00:01 host systemd[1]: myapp.service: Main process exited, code=exited, status=203/EXEC
Jun 05 10:00:01 host systemd[1]: myapp.service: Failed with result 'exit-code'.

O que ler:

• Loaded: -- o caminho da unit e enabled / disabled. Se mostra not-found, a própria unit não está sendo encontrada.
• Active: -- failed significa que iniciou e morreu. activating (auto-restart) significa que está preso em um loop de reinicialização.
• Result: -- exit-code (saída não-zero) / timeout (início não completou no tempo) / signal (morto por um sinal) / start-limit-hit (reiniciou muitas vezes).
• status=NNN/NAME -- o exit code. Como mostrado abaixo, valores 2xx carregam significado específico do systemd.

Como ler o log de falha com journalctl?

Conclusão: journalctl -xeu <servico> é o comando chave. -u limita ao serviço, -e pula para o final, -x adiciona dicas explicativas do systemd. O próprio erro da aplicação (command not found, Permission denied, bind: address already in use) aparece aqui.

# Ler o final, limitado ao servico (mais comum)
$ journalctl -xeu myapp

# Limitar aos ultimos minutos
$ journalctl -u myapp --since "5 min ago"

# Limitar ao boot atual
$ journalctl -b -u myapp

Para um código de origem do systemd como status=203/EXEC, a própria mensagem de erro da aplicação frequentemente aparece apenas no journal. Cruze ambos.

O que significam os exit codes 203 / 200 / 217?

Conclusão: O systemd atribui exit codes dedicados 200-243 para falhas durante a configuração de inicialização. Os comuns são 203/EXEC (executável ausente ou sem permissão de execução), 200/CHDIR (WorkingDirectory não existe) e 217/USER (a conta User= não existe). Eles são distintos dos códigos genéricos que uma aplicação retorna.

Leia status=NNN/NAME na linha Main PID. Um valor 2xx sinaliza "o systemd falhou antes da aplicação executar", o que quase sempre aponta a causa para a configuração da unit.

# Isolando 203/EXEC: verificar o caminho e permissao de execucao
$ systemctl cat myapp | grep ExecStart
ExecStart=/opt/myapp/bin/server --config /etc/myapp.conf

$ ls -l /opt/myapp/bin/server      # existe? tem o bit x?
$ head -1 /opt/myapp/bin/server    # se e um script, verifique o shebang

Como verificar o conteúdo e a sintaxe da unit?

Conclusão: Não leia o arquivo original que você editou; leia o que está efetivamente em vigor com systemctl cat <servico>. Ele também mescla quaisquer overrides drop-in (*.d/*.conf). Valide a sintaxe mecanicamente com systemd-analyze verify.

# Mostrar a unit efetiva, incluindo drop-ins
$ systemctl cat myapp

# Validar a sintaxe e referencias da unit
$ systemd-analyze verify /etc/systemd/system/myapp.service

systemd-analyze verify avisa sobre diretivas desconhecidas, dependências irresolúveis e ExecStart ausente. Nenhuma saída significa nenhum problema de sintaxe.

Erros comuns de configuração:

• Incompatibilidade de Type=: definir Type=forking para um processo que fica em foreground faz o systemd esperar por um filho que nunca vem, e então expirar. Se seu processo não faz fork e daemonize, use Type=simple (o padrão).
• ExecStart relativo: como acima, um caminho absoluto é necessário.
• Variáveis de ambiente ausentes: o .bashrc de um shell interativo não é lido. Defina-as explicitamente com Environment= ou EnvironmentFile=.

Por que minha edição não entra em vigor?

Conclusão: O systemd armazena os arquivos de unit em cache na memória. Se você não executar systemctl daemon-reload após a edição, ele inicia com a definição antiga. Esta é a causa clássica de "corrigi mas recebo o mesmo erro".

$ sudo vim /etc/systemd/system/myapp.service
$ sudo systemctl daemon-reload      # <- pule isso e sua edicao e ignorada
$ sudo systemctl restart myapp

Quando o daemon-reload está ausente, systemctl cat mostra o conteúdo editado enquanto o comportamento de inicialização ainda usa a definição antiga -- uma inconsistência confusa. Faça de edição -> daemon-reload -> restart um hábito único.

Isolando permissões, dependências e timeouts

Conclusão: Quando a aplicação funciona manualmente mas falha como serviço, as causas usuais são privilégios insuficientes para o usuário de execução, um serviço de dependência que ainda não está ativo, ou um timeout de inicialização. Verifique as permissões de User=, After=/Requires= e TimeoutStartSec em ordem.

Permissões (funciona manualmente, Permission denied como serviço)

systemctl start executa como User= (root por padrão). Se isso difere do usuário com o qual você testou, o acesso a arquivos, portas ou sockets pode falhar com Permission denied.

# Reproduzir manualmente como o usuario de execucao do servico
$ sudo -u myappuser /opt/myapp/bin/server --config /etc/myapp.conf

Se o erro se reproduzir, a causa está no lado da aplicação/permissão. Se não, suspeite da configuração da unit. Para o básico de permissões, veja Corrigindo Permission denied.

Dependências (um serviço necessário ainda não está ativo)

Se o serviço precisa de um banco de dados ou network-online mas a ordenação não está garantida, ele morre com falha de conexão logo após iniciar.

[Unit]
After=network-online.target postgresql.service
Wants=network-online.target

After= controla apenas a ordenação; Requires=/Wants= expressam a dependência. Revise isso para falhas de "o alvo ainda não está lá".

Timeouts (Result: timeout)

Se status mostra timeout, o serviço não sinalizou "início completo" dentro do padrão de 90 segundos. Para serviços com inicialização pesada, aumente TimeoutStartSec= ou use Type=notify para sinalizar prontidao explicitamente.

Como lidar com o loop "start request repeated too quickly"?

Conclusão: Após um número definido de falhas em uma janela curta (padrão StartLimitBurst=5 dentro de StartLimitIntervalSec=10s), o systemd suprime novas inicializações e relata start-limit-hit. Corrija a causa raiz, depois limpe o contador com systemctl reset-failed.

myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.

Esta mensagem é um resultado, não a causa. A razão real está nos logs de falha anteriores. Passos:

# 1) Voltar ate a razao real da falha
$ journalctl -xeu myapp

# 2) Corrigir a causa (ExecStart / permissoes / dependencias, etc.)

# 3) Limpar o contador de falhas, depois iniciar
$ sudo systemctl reset-failed myapp
$ sudo systemctl start myapp

Checklist de diagnóstico

Conclusão: Trabalhe de cima para baixo -- status -> journalctl -> exit code -> conteúdo da unit -> daemon-reload -> permissões/dependências -> start-limit -- e você identificará quase qualquer Failed to start.

Verifique cada item em ordem.

• [ ] Leu Active: / Result: / status=NNN de systemctl status myapp
• [ ] Verificou o próprio erro da aplicação em journalctl -xeu myapp
• [ ] Identificou o exit code (203/EXEC, 200/CHDIR, 217/USER são problemas de configuração da unit)
• [ ] Confirmou a unit efetiva com systemctl cat myapp; ExecStart é um caminho absoluto
• [ ] Validou a sintaxe com systemd-analyze verify
• [ ] Executou systemctl daemon-reload após editar a unit
• [ ] Type= corresponde ao comportamento do processo (se ele faz fork)
• [ ] Reproduziu com sudo -u <User> para isolar permissões, dependências e timeouts
• [ ] Limpou start-limit-hit com reset-failed somente após corrigir a causa