HTTP Error 502.5 ANCM 시작 실패

Problem

ASP.NET Core 사이트를 IIS 뒤에 배포했습니다. 브라우저로 접속하면 HTTP Error 502.5 - ANCM Out-Of-Process Startup Failure(또는 최신 앱에선 HTTP Error 500.30 - ANCM In-Process Start Failure)가 뜹니다. IIS는 분명히 살아 있습니다 — 그 페이지를 생성했으니까요 — 하지만 당신의 애플리케이션은 아닙니다. 오류는 짧고, 일반적이며, 앱이 왜 시작되지 않았는지는 전혀 알려 주지 않습니다. 바로 그게 함정입니다: 진짜 원인은 눈앞의 화면이 아니라 아직 열어 보지 않은 로그에 있습니다.

Symptoms

• 사이트가 모든 요청에 502.5(또는 500.30/500.31)를 반환합니다; 앱은 응답을 서빙하지 못합니다.
• 배포, 서버 재구축, .NET 버전 상향 직후에 나타납니다.
• 브라우저 페이지가 ANCM — ASP.NET Core 모듈 — 을 언급하고 “Out-Of-Process Startup Failure” 또는 “In-Process Start Failure”라고 합니다.
• IIS 워커 프로세스는 돌고 있지만, 앱용 dotnet 프로세스는 없거나(out-of-process), 워커가 요청마다 재활용됩니다(in-process).
• 외부 HTTP 점검은 서버에서 깔끔한 5xx를 보여 줍니다 — 네트워크 경로·DNS·TLS는 모두 정상이고 앱만 다운된 것입니다.

What 502.5 Actually Means

IIS는 ASP.NET Core 앱을 직접 실행하지 않습니다. 네이티브 모듈 — ASP.NET Core 모듈(ANCM) — 이 IIS 안에 앉아, 앱의 Kestrel 기반 프로세스를 띄우고 요청을 그리로 전달하는 책임을 집니다. 호스팅 모델은 둘입니다. Out-of-process: ANCM이 dotnet.exe(또는 게시된 실행 파일)를 동적으로 할당된 포트를 듣는 별도 프로세스로 띄우고 IIS가 리버스 프록시합니다. In-process(ASP.NET Core 3.0부터 기본값): 더 낮은 지연을 위해 앱을 IIS 워커 프로세스 안에서 로드해 실행합니다.

502.5는 out-of-process 실패입니다. 502는 게이트웨이 오류입니다 — “백엔드로 프록시하려 했는데 거기 아무것도 없었다” — 그리고 실제로 그 일이 일어났습니다: ANCM이 워커 프로세스를 시작하려 했는데 올라오지 않았거나(또는 올라왔다 즉시 종료됐거나), IIS가 대화할 Kestrel이 없는 것입니다. in-process 등가물은 대신 500.30을 던집니다 — 게이트웨이로 넘길 별도 백엔드가 없어서, 실패가 IIS 자신의 프로세스 안에 있기 때문입니다. 같은 병, 두 오류 번호, 결정하는 건 오직 web.config가 고른 hostingModel입니다.

핵심적으로 새겨야 할 것: 어느 번호도 오류 그 자체가 아닙니다. 둘 다 IIS가 당신의 프로세스가 시작에 실패했다고 보고하는 것이지, 왜 실패했는지가 아닙니다. “왜”는 시작 예외, 누락된 런타임, 잘못된 실행 경로이고 — 브라우저가 절대 보여 주지 않는 어딘가에 기록돼 있습니다. 502.5 페이지를 다시 읽는 데 쓰는 1분은 정답을 실제로 쥐고 있는 stdout 로그를 읽지 않는 1분입니다.

Top 3 Causes

1. .NET 런타임이 누락되었거나 버전이 틀림. framework-dependent 앱은 일치하는 ASP.NET Core Runtime — ANCM도 함께 등록하는 Hosting Bundle로 설치 — 이 서버에 있어야 합니다. 새 서버엔 없고, .NET 6이 있는 서버는 .NET 8 앱을 시작하지 못합니다. 단서: 갓 만든/재구축한 박스이고, dotnet --list-runtimes에 앱이 타깃하는 버전의 Microsoft.AspNetCore.App이 없습니다. 맞는 메이저 버전의 Hosting Bundle을 설치하고 iisreset을 실행하세요.
2. 앱이 시작 중에 예외를 던짐. 잘못된 연결 문자열, 누락된 환경 변수, Program.cs/Startup의 예외, 실패한 DI 등록, 앱이 못 읽는 설정 파일 — 호스트 빌드가 끝나기 전에 죽는 것은 무엇이든 502.5/500.30으로 표출됩니다. 단서: dotnet --list-runtimes는 정상이고, stdout 로그(또는 애플리케이션 이벤트 로그)에 스택 트레이스가 있는 진짜 .NET 예외가 보입니다. 그 예외를 읽으세요; 그게 바로 버그입니다.
3. 잘못된 실행 경로 또는 깨진 게시. web.config의 aspNetCore 요소가 processPath/arguments를 없는 실행 파일이나 DLL로 지목합니다 — 불완전한 게시, 누락된 <AppName>.dll, framework-dependent와 self-contained 출력의 불일치, 손상된 배포. 단서: stdout 로그가 비었거나 프로세스가 로드조차 못 하고 실패하며, 게시 폴더에 web.config가 지목한 진입점 DLL이 없습니다. 깨끗이 재게시하고 출력이 processPath와 일치하는지 확인하세요.

Diagnose with DechoNet

• HTTP Check는 서버가 타임아웃이나 연결 거부가 아니라 진짜 5xx로 응답하는지 확인합니다 — IIS는 살아 있고 실패는 네트워크·다운된 오리진·방화벽이 아니라 당신의 앱 프로세스라는 증거입니다.
• Port Check는 80/443이 열려 연결을 받는지 검증해, “IIS는 듣고 있는데 앱이 안 뜬다”(502.5)와 “아무것도 안 듣는다”(정지된 사이트나 차단된 포트)를 구분하게 해 줍니다.
• DNS Check는 호스트명이 당신이 실제로 배포 중인 서버를 가리키는지 확인합니다 — 편집이 트래픽을 서빙하는 박스가 아닌 다른 박스에 적용돼 “수정이 안 먹히는” 경우가 의외로 흔합니다.

Resolution Checklist

• 서버에서 dotnet --list-runtimes를 실행해 Microsoft.AspNetCore.App에 앱이 타깃하는 메이저 버전이 포함되는지 확인하세요. 없으면 ASP.NET Core Hosting Bundle을 설치하고 iisreset을 실행하세요.
• stdout 로그를 켜세요: web.config에 stdoutLogEnabled="true"와 stdoutLogFile=".\logs\stdout"을 설정하고, logs 폴더를 직접 만들고, 앱 풀 ID에 쓰기 권한을 주세요. 재현한 뒤 로그를 읽으세요.
• Windows 애플리케이션 이벤트 로그에서 ASP.NET Core 모듈 항목을 확인하세요 — 시작 실패는 stdout 로깅이 꺼져 있어도 거기 기록됩니다.
• hostingModel과 진입점이 일치하는지 확인하세요: web.config의 processPath/arguments는 게시 출력에 실제로 존재하는 실행 파일이나 dotnet <AppName>.dll을 가리켜야 합니다.
• 서버에서 앱을 직접 실행해 보세요(게시 폴더에서 dotnet YourApp.dll) — 콘솔에서 같은 예외로 죽으면 문제를 IIS나 ANCM이 아니라 앱으로 좁힌 것입니다.
• 고친 뒤 stdout 로깅을 다시 끄세요 — 진단용이지 프로덕션용이 아니고, 로그 파일이 무한히 커집니다.

When to Escalate

• dotnet --list-runtimes가 맞는 런타임을 보여 주는데 stdout 로그가 완전히 비었으면(파일 미생성, 이벤트 로그에도 없음), ASP.NET Core 모듈 자체가 없거나 불일치일 수 있습니다 — web.config를 더 편집하지 말고 ANCM을 다시 등록하는 Hosting Bundle을 재설치하세요.
• 콘솔에서 dotnet YourApp.dll로는 잘 시작되는데 IIS 아래서만 실패하면, 차이는 환경이나 ID입니다: 앱 풀은 다른 프로필·환경 변수·파일 권한을 가진 다른 사용자로 실행됩니다. 코드가 틀렸다고 단정하기 전에 IIS 아래서 앱이 보는 환경을 콘솔과 비교하세요.