리눅스에서 서비스를 운영하다 보면
systemctl status 출력에서 아래와 같은 상태를 자주 보게 된다.

• Active: failed (Result: exit-code)
• Unit entered failed state

이 메시지는 systemd가 해당 서비스를 정상적으로 실행하지 못했다고 판단했다는 의미다.
아래는 이 에러를 빠르게 진단하고 처리하는 3단계 루틴이다.

---

서비스 상태 및 종료 원인 확인 #

가장 먼저 서비스 상태와 종료 사유를 확인한다.

sudo systemctl status [서비스명]

여기서 반드시 확인할 포인트는 다음이다.

• Main PID
  종료된 프로세스 ID와 종료 시점의 상태
• Result
  • exit-code
    → 프로그램 내부 오류로 정상 종료하지 못함
  • signal
    → 외부 신호로 강제 종료됨 (OOM Killer 등)

이 단계에서는
“어디서 죽었는지”가 아니라
“어떤 유형으로 죽었는지”만 파악하면 된다.

---

journalctl로 상세 로그 분석 (핵심) #

systemctl status만으로는 정보가 부족한 경우가 대부분이다.
실제 원인은 journal 로그에 거의 다 나온다.

sudo journalctl -u [서비스명] -n 50 --no-pager

여기서 아래 메시지들이 가장 많이 등장한다.

• Permission denied
  → 실행 파일, 설정 파일, 로그 디렉터리 권한 문제
• Address already in use
  → 포트 충돌 (이미 다른 프로세스가 사용 중)
• syntax error, invalid config
  → 설정 파일 문법 오류
• Out of memory, Killed process
  → 메모리 부족으로 커널이 프로세스 강제 종료

이 단계에서 원인 대부분은 결정된다.

---

대표적인 원인과 해결 정리 #

원인	확인 방법	해결 방법
설정 파일 오류	journalctl 내 syntax error 확인	.conf, .yaml 문법 수정
권한 문제	ls -l로 파일/디렉터리 권한 확인	chown, chmod로 권한 수정
포트 충돌	ss -tulpn | grep [포트]	기존 프로세스 종료 또는 포트 변경
종속성 문제	systemctl list-dependencies [서비스명]	선행 서비스 먼저 실행

---

설정 변경 후 반드시 해야 할 작업 #

.service 파일이나 설정 파일을 수정했다면
바로 restart 하면 안 된다.

sudo systemctl daemon-reload
sudo systemctl restart [서비스명]

daemon-reload 없이 재시작하면
systemd가 이전 설정을 그대로 들고 있는 경우가 많다.

---

요약 #

1. systemctl status로 실패 유형 확인
2. journalctl -u로 실제 원인 파악
3. 설정 수정 후 daemon-reload → 재시작

이 루틴으로
systemd failed 상태의 대부분은 5분 안에 정리 가능하다.

🛠 마지막 수정일: 2025.12.22