홈/엔지니어/트러블슈팅/Docker 컨테이너 계속 재시작될 때 — Exit…
트러블슈팅초급UbuntuDebianCentOSDockerRestartingExited

Docker 컨테이너 계속 재시작될 때 — Exit code별 원인과 해결 방법

docker ps에서 Restarting 또는 Exited 상태가 반복될 때 로그·exit code·restart policy를 확인해 원인을 진단하고 해결하는 가이드.

목차

    1차 출처

    의사결정표: Exit Code와 그에 따른 원인 및 해결방법

    Exit code의미주요 원인해결 방법
    0정상 종료컨테이너 작업이 끝남 (의도된 종료)확인 필요 없음
    1앱 오류애플리케이션 런타임 에러로그 검토, 환경변수 및 포트 확인 (docker logs, docker inspect)
    137SIGKILLOOM Killer 또는 docker kill메모리 사용량 확인, 제한 늘리기 (docker stats, docker run -m 512m, docker-compose.yml mem_limit: 512m)
    139Segfault앱 메모리 충돌코드 디버깅 및 메모리 관리 개선 필요
    143SIGTERMdocker stop 이후 정상 종료확인 필요 없음

    Step 1 — 상태와 exit code 확인

    Bash
    # 모든 컨테이너 상태 (중지된 것 포함)
    docker ps -a
    
    # 출력 예
    # CONTAINER ID  IMAGE    STATUS                     NAMES
    # abc123        myapp    Restarting (1) 5s ago      myapp
    # def456        nginx    Exited (137) 2 minutes ago nginx
    #                        ↑ exit code

    Step 2 — 컨테이너 로그 확인

    Bash
    # 마지막 100줄 로그
    docker logs --tail 100 컨테이너명
    
    # 실시간 로그 (재시작 반복 중 확인)
    docker logs -f 컨테이너명
    
    # 타임스탬프 포함
    docker logs -t --tail 50 컨테이너명
    
    # 중지된 컨테이너 로그도 볼 수 있음
    docker logs 컨테이너ID

    Exit code 1 — 앱 크래시

    로그에서 에러 메시지를 확인합니다.

    Bash
    docker logs 컨테이너명 2>&1 | tail -30

    주요 원인:

    • 환경변수 누락: Error: DATABASE_URL is not defined
    • 포트 충돌: Error: listen EADDRINUSE :::3000
    • 파일/설정 없음: No such file or directory
    Bash
    # 환경변수 확인
    docker inspect 컨테이너명 | grep -A 20 '"Env"'
    
    # 컨테이너 안에서 직접 확인 (일회성 실행)
    docker run --rm -it --env-file .env 이미지명 /bin/sh

    Exit code 137 — OOM 강제 종료

    Bash
    # OOM으로 죽었는지 확인
    docker inspect 컨테이너명 | grep -i oom
    # "OOMKilled": true 이면 OOM
    
    # 메모리 사용량 확인
    docker stats --no-stream 컨테이너명
    Bash
    # 메모리 제한 늘리기 (docker run)
    docker run -m 512m 이미지명
    
    # docker-compose.yml
    # services:
    #   myapp:
    #     mem_limit: 512m

    restart policy 확인·변경

    Bash
    # 현재 restart policy 확인
    docker inspect 컨테이너명 | grep -A 3 'RestartPolicy'
    Policy동작
    no재시작 안 함 (기본값)
    always항상 재시작 (exit code 무관)
    on-failure비정상 종료(non-0)만 재시작
    unless-stopped수동 중지 전까지 항상 재시작
    Bash
    # 재시작 반복이 문제라면 policy를 on-failure로 변경
    docker update --restart=on-failure:5 컨테이너명
    # 5회 시도 후 중지
    
    # 완전히 중지
    docker update --restart=no 컨테이너명
    docker stop 컨테이너명

    디버깅 — 컨테이너를 수동으로 시작

    Bash
    # entrypoint 무시하고 쉘로 진입 (원인 직접 파악)
    docker run --rm -it --entrypoint /bin/sh 이미지명
    
    # 기존 컨테이너 설정 그대로 쉘 진입
    docker run --rm -it   $(docker inspect 컨테이너명 --format '{{range .Config.Env}}-e {{.}} {{end}}')   --entrypoint /bin/sh   이미지명

    자주 묻는 질문 (FAQ)

    Q. docker ps에서 계속 Restarting 상태입니다. 어디부터 보나요? A. docker logs <컨테이너>로 종료 직전 로그를 먼저 봅니다. 그다음 docker inspect <컨테이너> --format '{{.State.ExitCode}}'로 종료 코드를 확인하세요. 137=OOM(메모리 초과), 1·2=앱 예외, 126·127=실행 파일·권한 문제입니다. restart 정책이 always면 앱이 죽을 때마다 무한 재시작하므로, 원인을 잡기 전엔 --restart=no로 바꿔 로그를 확보하는 게 편합니다.

    #Docker#Restarting#Exited#exit code#트러블슈팅#restart policy#container
    편집 안내 · Editorial Note

    AI 도구가 초안 작성에 사용될 수 있습니다. 명령어의 실행 여부와 검증 환경은 각 가이드에 기재된 근거를 확인하세요. 적용 전 사용 중인 버전의 공식 문서를 확인하고, 오류는 이메일로 알려주세요. 이메일로 제보

    주제 관련 공식 문서(자동 연결 · 문장별 근거 아님)Docker 공식 문서 ↗

    질문 & 답변 (Q&A)

    이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.