systemd start-limit-hit 해결: 최초 실패를 고친 뒤 reset-failed로 복구

 

직접 생성한 개념 이미지입니다. 실제 서비스 화면이나 구축·성능 시험 결과가 아닙니다.

start-limit-hit나 Start request repeated too quickly가 보이면 먼저 제한에 도달하기 전의 최초 실패 로그를 찾으세요. reset-failed는 실패 상태와 시작 제한 카운터를 정리하지만 프로그램의 오류를 수정하지 않습니다. 원인을 고친 다음 대상 서비스만 재개하고 재발 여부를 확인해야 합니다.

원인: 마지막 메시지는 시작을 막은 결과일 수 있다

서비스가 짧은 시간에 여러 번 시작되면 systemd의 시작 횟수 제한에 걸릴 수 있습니다. 자동 재시작뿐 아니라 수동 시작도 해당 제한과 관계되므로 같은 start 명령을 연속 실행해 해결하려고 하면 진단이 더 어려워집니다. 마지막 제한 메시지 앞에 설정 누락, 실행 파일 오류, 의존 대상 접근 실패 같은 실제 원인이 있는지 살펴보세요.

기록	의미	다음 점검
최초 프로세스 오류	시작 실패 원인	설정·실행 조건
start-limit-hit	시작 횟수 제한	앞선 실패 로그
reset-failed 후 재실패	원인 미해결 가능	변경 내용과 새 로그
active 표시	실행 상태	실제 기능 응답

1. 서비스 이름과 범위를 확인하고 로그를 보존한다

다음은 시스템 서비스의 읽기 전용 진단 예시입니다. 실제 서비스 이름으로 바꾸고 로그를 읽을 권한이 있는 계정에서 사용하세요. 사용자 서비스라면 systemctl --user와 해당 사용자 journal을 사용해야 하며 시스템 범위의 결과와 섞지 않습니다. 출력에는 환경 정보가 들어갈 수 있으므로 외부 공유 전 비밀값을 제거합니다.

systemctl --version
systemctl status app.service --no-pager -l
journalctl -u app.service -b -n 100 --no-pager
systemctl cat app.service

최초 실패가 최근 100줄보다 앞에 있다면 장애가 발생한 시간 범위를 지정해 더 이전 기록을 확인합니다. 재부팅 전 장애라면 현재 부팅의 -b 범위에 없을 수 있습니다. 보존된 journal 범위를 먼저 확인하고 “로그가 없다”를 “오류가 없었다”로 해석하지 마세요.

2. 가장 먼저 실패한 원인을 한 가지씩 수정한다

203/EXEC가 먼저 보이면 실행 경로·권한·인터프리터를, 애플리케이션이 자체 오류 코드를 내면 설정과 의존 서비스 상태를 점검합니다. unit 파일의 ExecStart와 drop-in 설정도 실제 설치 버전에 맞춰 읽습니다. root로 실행하면 된다는 식으로 사용자 범위를 넓히거나 보안 검사를 꺼서 정상처럼 만들지 않습니다.

시작 제한 설정인 StartLimitIntervalSec·StartLimitBurst와 재시작 정책은 다른 역할입니다. 제한값을 무조건 키우거나 0으로 꺼서 반복 실패를 감추는 방식은 피하세요. 실제 재시작 간격과 장애 시 서비스가 외부 시스템에 주는 영향을 확인한 뒤 별도 운영 정책으로 정합니다. 배포판과 설치 버전의 문서가 최종 기준이며 이 글은 기본 횟수·초를 모든 환경에 동일하게 가정하지 않습니다.

3. 원인을 고친 뒤 대상 서비스만 다시 시작한다

아래는 수정 검토가 끝난 후 승인된 운영 시간이나 시험 환경에서만 수행할 복구 예시입니다. unit 또는 drop-in 파일을 수정했을 때는 daemon-reload가 필요할 수 있습니다. 애플리케이션의 일반 설정 파일만 바꾼 경우와 구분하세요. 실행 전 원본 설정을 보존하고 되돌릴 변경 범위를 정합니다.

# unit/drop-in을 수정한 경우에 적용
sudo systemctl daemon-reload
# 최초 원인 수정 후, 대상 서비스에만 적용
sudo systemctl reset-failed app.service
sudo systemctl start app.service
systemctl status app.service --no-pager -l

reset-failed에 서비스 이름을 생략하면 범위가 넓어지므로 이 예시에서는 대상을 명시합니다. 이 명령 자체가 서비스를 시작하거나 고장 난 프로그램을 고치는 것은 아닙니다. start 후 같은 오류가 반복된다면 다시 reset-failed를 반복하기보다 새 로그와 수정한 조건을 비교합니다.

확인 방법: 실행 상태와 실제 서비스 응답을 따로 확인한다

active 상태를 확인한 다음 해당 서비스가 제공하는 정상 기능을 승인된 점검 경로로 확인합니다. 웹 서비스라면 실제 점검용 요청, 작업 서비스라면 허용된 시험 작업을 사용합니다. 순간적으로 active였다가 종료되는지와 의도한 정상 종료 유형인지도 구분하세요. 이 글의 명령은 공식 문서 기반 예시이며 실제 서버에서 실행한 시험 결과가 아닙니다.

복구 후에는 장애 전 최초 오류, 수정한 항목, 재시작 시각, 관찰한 결과를 남깁니다. 변경으로 다른 문제가 생기면 보존한 해당 설정을 되돌리고 필요한 reload·시작 절차를 다시 검토합니다. 재시작 성공 화면만으로 업무 정상이나 데이터 정합성을 보장하지 않습니다.

FAQ

시간이 지나면 자동으로 다시 시작하나요? 제한 시간이 지났다는 이유만으로 자동 재개를 단정하지 마세요. 트리거와 재시작 정책·현재 상태를 확인해야 합니다.

reset-failed만 반복해도 되나요? 최초 오류가 남아 있으면 같은 제한에 다시 도달할 수 있습니다.

기본 제한은 항상 같나요? 관리자 설정과 배포판·설치 버전에 따라 확인해야 합니다.

공식 출처와 관련 글

자료 확인일: 2026년 10월 17일. 공식 문서 기반 설명이며 실제 서비스·명령 실행 시험은 수행하지 않았습니다. 설치 버전과 리전·지원 범위는 적용 전에 확인하세요.

systemd.unit 시작 횟수 제한

systemctl reset-failed 동작

systemd 서비스 재시작 설정

관련 글: 최초 오류가 203/EXEC일 때 실행 경로·인터프리터 확인

적용 전 원본 설정을 보존하고 승인된 시험 범위에서 결과를 확인하세요.