ECONNRESET (Connection reset by peer)

ECONNRESET은 Node.js가 사용하는 시스템 오류 코드입니다. 연결 상대 또는 현재 애플리케이션이 소켓을 정상적인 응답 완료 전에 닫았다는 뜻입니다. HTTP 상태 코드가 아니며, 오류 코드만으로 서버·프록시·클라이언트 중 어느 구간이 연결을 닫았는지는 확정할 수 없습니다.

브라우저 화면에 ERR_CONNECTION_RESET 또는 연결이 재설정되었습니다가 표시된 경우에는 브라우저 ERR_CONNECTION_RESET 확인 절차를 사용합니다. 이 문서는 Node.js 애플리케이션 로그의 ECONNRESET, read ECONNRESET, socket hang up을 확인할 때 사용합니다.

먼저 확인할 값

1. 오류 객체의 error.code가 정확히 ECONNRESET인지 확인합니다.
2. 오류가 요청 객체에서 발생했는지, 응답 객체에서 발생했는지 확인합니다.
3. 요청 메서드, 대상 호스트·포트, 발생 시각과 요청 식별자를 기록합니다.
4. Node.js HTTP 요청이면 request.reusedSocket 값을 기록합니다.
5. 같은 시각의 대상 서버와 중간 프록시 로그에서 연결 종료·재시작·시간 제한 기록을 확인합니다.

오류 메시지 문자열은 Node.js 버전에 따라 바뀔 수 있으므로 socket hang up이나 read ECONNRESET만 비교하지 않습니다. 분류 기준은 error.code입니다.

발생 단계를 구분합니다

Node.js 공식 HTTP 문서는 응답 전 연결 종료와 응답 중 연결 종료에서 발생하는 이벤트가 다르다고 설명합니다. 요청 객체의 error만 기록하지 말고 응답 객체의 aborted, close, error도 같은 요청 식별자로 기록해야 합니다.

재사용 소켓을 확인합니다

keep-alive를 사용하는 HTTP Agent는 기존 소켓을 다음 요청에 재사용할 수 있습니다. 서버가 유휴 소켓을 닫는 시점과 다음 요청이 겹치면 재사용 요청에서 ECONNRESET이 발생할 수 있습니다.

request.on("error", (error) => {  console.error({    code: error.code,    reusedSocket: request.reusedSocket,  });});

허용된 점검 환경에서 같은 읽기 요청을 새 연결로 한 번 실행해 비교할 수 있습니다. Node.js의 http.get() 또는 http.request()에 agent: false를 지정하면 해당 요청에 일회용 Agent를 사용합니다. 이 비교로 오류가 사라지고 reusedSocket이 true였다는 관찰값이 함께 있어야 연결 재사용 구간을 우선 확인할 수 있습니다. 운영 전체에서 keep-alive를 끄는 것은 진단 결과가 아닙니다.

수정 범위를 결정합니다

• 대상 서버 또는 프록시가 응답 전에 연결을 닫았다면 같은 시각의 서버·프록시 로그에서 종료 조건을 확인하고 해당 조건만 수정합니다.
• 응답 본문 전송 중 연결이 닫혔다면 응답 크기, 처리 시간과 중간 서버의 연결 종료 기록을 같은 요청으로 비교합니다.
• 재사용 소켓에서만 재현되면 클라이언트와 서버의 keep-alive 설정과 유휴 연결 종료 시점을 비교합니다.
• 현재 코드의 destroy()가 원인이면 시간 제한 이벤트를 받은 뒤 실제로 어떤 분기가 연결을 닫는지 수정합니다. AbortController.abort()는 ABORT_ERR로 구분합니다.

Node.js 공식 예시는 request.reusedSocket === true이면서 error.code === "ECONNRESET"인 요청의 재시도를 보여 줍니다. 이 예시를 모든 요청에 적용하지 않습니다. 결제·주문·회원 가입처럼 중복 실행이 가능한 요청은 서버의 멱등성 보장이나 요청 식별자 없이 자동 재시도하지 않습니다.

수정 후 재확인합니다

1. 처음 실패한 것과 같은 메서드·대상·입력 조건으로 요청을 다시 실행합니다.
2. 요청과 응답 본문이 끝까지 완료됐는지 확인합니다.
3. 같은 요청 식별자의 클라이언트·프록시·대상 서버 로그에 ECONNRESET이 다시 기록되지 않았는지 확인합니다.
4. 재시도를 추가했다면 실제 전송 횟수와 중복 처리 여부를 확인합니다.

공식 근거

• Node.js Errors 문서 (새 창에서 열림)
• Node.js HTTP 문서 (새 창에서 열림)