오류 코드와 문제 해결

원문 보기 위키 갱신 2026.10.08

Fly.io 플랫폼은 고객 로그 스트림에 오류를 기록해요. 각 로그 줄에는 오류 코드와 그 코드를 담은 필드가 있습니다. 이 페이지에서는 각 오류가 무엇을 의미하는지와 어떻게 문제를 해결할 수 있는지 자세히 설명합니다.

출처: 문서

본문

Fly.io 플랫폼은 오류를 고객 로그 스트림에 기록합니다. 각 로그 줄에는 오류 코드와 그 코드를 담은 필드가 있어요. 이 페이지는 오류에 대한 더 많은 맥락과 문제 해결 방법을 제공합니다.

프록시 오류 (Proxy errors)

Fly 프록시는 각 코드의 두 번째 글자로 식별되는 여러 유형의 오류를 발생시킵니다. Upstream, Connection, TLS, Machine, App, Edge, Routing 오류를 가리킵니다.

내부 오류 (Internal Errors)

이 오류들은 Fly 프록시 내부의 오류예요. 애플리케이션 동작과 관련이 없습니다.

PP01: TCP 소켓 옵션 설정 실패

프록시가 TCP 소켓 옵션을 설정하지 못했습니다. Fly.io 내부 오류예요.

Upstream 프록시 오류

Upstream 오류는 프록시가 업스트림 애플리케이션 머신 중 하나에 요청을 보내거나 완료하지 못할 때 발생해요.

PU01: HTTP/2 핸드셰이크 실패

앱이 h2c 요청을 수락하는 경우 PU01 오류는 머신 중 하나로의 HTTP/2 핸드셰이크가 실패했음을 나타냅니다. 이 오류는 HTTP/1 연결만 수락하는 애플리케이션에는 관련이 없어요.

PU02: 인스턴스로의 HTTP 요청 완료 실패

머신으로의 HTTP 요청이 시작됐지만 완료되지 않았습니다.

PU03: 도달할 수 없는 워커 호스트

머신이 사는 기본 호스트가 도달 불가능해졌어요. 애플리케이션과 무관한 Fly.io 내부 오류입니다.

PU04: HTTP 요청을 만들 수 없음

알 수 없는 이유로 HTTP 요청을 만들 수 없었습니다.

PC01: Machine이 포트에서 연결을 거부함

대상 머신에서 열려 있지 않은 특정 포트로 요청이 전송되었습니다.

앱이 올바른 포트에서 듣고 있나요?

앱이 0.0.0.0 또는 ::에서 듣고 있나요? 127.0.0.1에서 듣고 있지 않은지 확인하세요. 앱 시작 로그를 확인해 보세요. 서버는 보통 듣고 있는 주소를 출력합니다.

PC02: 연결 거부

대상 머신에서 열려 있지 않은 불특정 포트로 요청이 전송되었습니다.

PC03: 연결 재설정

애플리케이션이 TCP 연결을 너무 일찍 재설정하는 문제를 나타냅니다. 가능한 원인은 애플리케이션 로그를 확인해 보세요.

PC04: 연결 중단

애플리케이션이 TCP 연결을 너무 일찍 중단하는 문제를 나타냅니다. 가능한 원인은 애플리케이션 로그를 확인해 보세요.

PC05: 연결 시간 초과

애플리케이션으로의 연결이 시간 초과되는 문제를 나타냅니다. 진단하려면 다음을 확인하세요.

애플리케이션 로그가 시간 초과의 원인을 나타낼 수 있어요
동시성 한도를 제대로 설정해 앱이 과부하되지 않았는지 확인하세요
애플리케이션 메트릭에서 리소스 고갈(CPU, 메모리, 디스크 I/O) 징후를 확인하세요

PC06: 식별되지 않은 I/O 오류

머신으로의 연결에서 식별할 수 없는 I/O 오류가 발생했습니다.

PC07: 연결 재시도 소진

프록시가 너무 많은 재시도 끝에 머신에 연결하지 못했습니다.

PC08: TCP 시간 초과를 설정할 수 없음

업스트림 연결의 TCP 시간 초과를 설정하지 못했습니다. Fly.io 내부 문제예요.

TLS 오류

TLS 오류는 Fly Proxy가 제공하는 자동 TLS 종료(termination)와 관련됩니다. 이 오류는 요청이 애플리케이션으로 전달되기 전에 발생해요.

PT01: TLS 핸드셰이크 비율 제한 초과

특정 IP 범위가 TLS 핸드셰이크 시도의 비율 제한을 초과했습니다.

PT02: SNI 비율 제한 초과

특정 SNI에 대한 TLS 핸드셰이크 요청이 비율 제한을 초과했습니다.

PT03: TLS 핸드셰이크 취소

TLS 핸드셰이크가 너무 일찍 취소되었습니다.

PT04: TLS 핸드셰이크 실패

TLS 핸드셰이크가 실패했습니다.

PT05: SNI에 대한 유효한 TLS 인증서 없음

특정 서버 이름에 대한 TLS 인증서가 없어 연결이 중단되었습니다.

PT06: 유효한 TLS 인증서 없음

연결에 대한 TLS 인증서가 없어 연결이 중단되었습니다.

PT07: TLS 핸드셰이크 I/O 오류

불특정 I/O 오류로 TLS 핸드셰이크가 실패했습니다.

PT08: TLS 핸드셰이크 시간 초과

TLS 핸드셰이크가 시간 초과되었습니다.

PT09: 내부 TLS 오류

내부 TLS 오류가 발생했습니다.

Machine 관련 오류

이 오류 부류는 요청 시 머신을 시작·중지할 때 프록시가 어떻게 동작하는지와 관련됩니다.

PM01: Machines API 오류

Machines API가 오류를 반환했습니다. 기본 오류를 알 수 있다면 표시됩니다.

PM02: Machine 깨우기 내부 오류

Fly.io 내부 오류로 머신이 stopped에서 started 상태로 전환되지 못했습니다.

PM03: Machine 깨우기 시간 초과

머신을 stopped에서 started 상태로 전환하는 API 요청이 시간 초과되었습니다.

PM04: Machine 깨우기 파싱 오류

요청 파싱 오류로 머신이 stopped에서 started 상태로 전환되지 못했습니다.

PM05: Machine 연결 실패

프록시가 머신에 연결하지 못했습니다. 기본 오류를 알 수 있다면 표시됩니다.

PM06: 앱 이름 없음

Machines API는 개별 머신을 다루려면 앱 이름이 필요합니다. 그 앱 이름이 지정되지 않았어요.

PM07: Machine 상태 변경 실패

프록시가 머신을 중지하거나 시작하지 못했습니다. 기본 오류를 알 수 있다면 표시됩니다.

PM08: 시작 불가능한 Machine 상태

머신의 현재 상태(stopping이나 destroyed 같은)가 시작할 수 없는 상태라 시작하지 못했습니다. 이 메시지와 함께 상태가 표시됩니다.

PM09: 알 수 없는 Machine 상태

프록시가 머신의 현재 상태를 인식하지 못합니다.

PM10: Machine 시작 취소

Fly.io 내부 문제로 머신 시작이 너무 일찍 취소되었습니다.

PM11: 최근에 중지된 Machine

머신 상태는 Fly 프록시에 최종 일관성(eventually consistent) 방식으로 브로드캐스트됩니다. 따라서 엣지 프록시는 머신 상태에 대한 최신 그림을 갖고 있지 않을 수 있어요. 엣지 프록시에 started로 보이는 머신이 실제로는 최근에 중지되었을 수 있습니다.

엣지 프록시가 최근에 중지된 머신으로 요청을 전달하고, 요청을 처리할 다른 머신이 있다면 PM11 오류가 엣지 프록시에 반환됩니다. 이 오류는 프록시에게 머신의 stopped 상태를 알리고, 다른 머신으로 요청을 전달하라고 지시합니다.

엣지 프록시가 요청을 서비스할 수 있는 머신이 하나뿐이라고 판단하면 이 로직은 건너뜁니다. 최근에 중지되었더라도 요청이 그 머신으로 전달됩니다.

'near recent stopped'의 현재 임계값은 5분입니다.

PA01: 재생/재시도 버퍼 초과

fly-replay 응답 헤더 수신 가능성이나 실패한 요청 재시도를 대비해 Fly 엣지 프록시는 최대 10MB까지 요청을 버퍼링합니다.

요청이 10MB보다 커지면 버퍼링이 중지되어 요청을 재생하거나 재시도할 수 없게 됩니다. 이 경우 PA01이 발생합니다.

PA02: 과도한 fly-replay 헤더

'fly-replay' 응답 헤더가 요청을 재생한 뒤 애플리케이션은 정상적으로 응답하거나, fly-replay를 최대 10번까지 다시 발행할 수 있어요. fly-replay가 10번 이상 반환되면 PA02가 발생합니다.

PA03: 잘못된 fly-replay

앱이 잘못된 'fly-replay' 응답을 반환했습니다.

PA04: 재생 대상 앱을 찾을 수 없음

앱이 app 파라미터에 존재하지 않는 애플리케이션을 대상으로 하는 'fly-replay' 응답 헤더를 반환했습니다.

PA05: 승인되지 않은 재생 대상 앱

앱이 다른 Fly.io 조직에 속한 애플리케이션을 대상으로 하는 'fly-replay' 응답 헤더를 반환했습니다. 같은 조직의 앱만 서로 요청을 재생할 수 있어요.

엣지 프록시 오류

이 오류 부류는 엣지 프록시에서만 발생하는 Fly.io 내부 오류를 말합니다.

PE01: 재생 소스 앱을 찾을 수 없음

소스 앱 이름과 관련해 fly-replay를 사용하는 중 내부 오류가 발생했습니다.

PE02: 재생 소스 조직을 찾을 수 없음

소스 조직과 관련해 fly-replay를 사용하는 중 내부 오류가 발생했습니다.

라우팅 오류

이 부류는 프록시와 애플리케이션 사이의 요청 라우팅 오류를 말합니다.

PR01: 정상 머신 없음

요청을 전달할 정상(healthy) 머신을 찾지 못했습니다. 이 오류는 HTTP가 아닌 TCP 서비스에서 가장 흔해요. 이유는 다음과 같을 수 있습니다.

부팅 오류로 재시작 재시도 소진

앱 머신들이 부팅 오류로 재시작 재시도 횟수를 소진해 모두 중지되었을 수 있어요. 앱 로그와 fly status를 확인하세요.

볼륨이 있는 배포가 실패 중

앱이 볼륨을 사용하고 롤링 배포가 실패 중이라면 이 오류를 만날 수 있어요. 앱 로그와 fly status를 확인하세요.

immediate 배포 전략 사용

immediate 배포 전략을 사용하면 모든 현재 머신을 한 번에 교체하므로 다운타임과 일부 PR01 오류가 발생할 수 있어요.

앱 동시성 한도 도달

fly.toml에 설정된 동시성 한도는 앱의 머신들 사이에 트래픽을 어떻게 균형을 맞출지 정의합니다.

진단하려면 다음을 확인하세요.

앱이 CPU, 메모리, 디스크 I/O를 너무 많이 사용하는지
앱이 자체 동시성 한도를 적용하는지
데이터베이스 같은 외부 서비스로의 연결 풀이 고갈됐는지
앱에서 외부 서비스로의 연결이 느린지

PR02: Machine을 찾을 수 없음

요청이 엣지 프록시에서 전달된 후 Fly 프록시가 특정 머신 ID를 찾지 못했습니다. VM은 프록시가 요청을 받은 시점과 전달된 시점 사이에 종료됐을 가능성이 커요. 이 오류는 bluegreen 배포 중에 가장 흔합니다.

PR03: 재시도 후 후보 머신 없음

이 오류는 기능적으로 PR01과 유사해요. 다만 HTTP 서비스에만 적용되며, 프록시가 포기하고 이 오류를 발행하기 전에 최대 90회 재시도합니다. 이 오류는 또한 그 이전의 가장 최근 오류의 원인도 표시해야 합니다.

PR04: 재시도 후 후보 머신 없음

이 오류는 기능적으로 PR03과 유사하지만, 이전 오류를 표시하지 않습니다.

PR05: Statics 검색 실패

프록시가 지정된 Tigris 스토리지 버킷에서 정적 파일을 검색하지 못했습니다.

PL01: 연결 동시성 한도 우회