# 문제 해결 (/ko/docs/troubleshooting)

전송이 실패하면 응답 패널에 <strong>에코 없음</strong>이 표시되고, 무엇이 잘못되었는지 쉬운 말로 설명하며 다음에 시도할 것을 알려 줍니다. <strong>다시 시도</strong>는 한 번 더
보냅니다. 원본 오류는 <strong>통신</strong> 보기에 남아 있습니다. 아래에서 해당 메시지를 찾아보세요.

<Shot id="troubleshooting-no-echo" alt="실패한 전송: 응답 패널에 에코 없음, 연결 거부됨: localhost:9에서 수신 대기 중인 것이 없습니다라는 설명과 다시 시도 버튼이 표시됨" />

## 연결 [#connecting]

<Accordions type="single">
<Accordion title="연결 거부됨: …에서 수신 대기 중인 것이 없습니다">

서버의 머신은 응답했지만, 그 포트에서 연결을 받는 프로그램이 없습니다.

- 서버가 실행 중인지, 그리고 주소의 포트에서 실행 중인지 확인하세요. `3000`에서 실행 중인 로컬 서버는 `localhost:8080`으로는 접속되지 않습니다.
- 변수가 채워진 뒤의 주소를 확인하세요. `{{variable}}` 알약 위에 포인터를 올려 값을 보고, 페이지 헤더에서 어떤 환경이 활성인지 확인합니다.
- Docker나 가상 머신 안의 서버는 포트를 Mac으로 공개해야 합니다.

</Accordion>
<Accordion title="…호스트를 찾을 수 없습니다">

이름이 주소로 해석되지 않습니다. 철자, 네트워크, VPN을 확인하세요. 회사 네트워크 안에만 있는 호스트는 그 네트워크나 VPN이 필요합니다.

</Accordion>
<Accordion title="…에서 제시간에 응답이 없습니다 / …에 제시간에 연결하지 못했습니다">

<strong>…에서 제시간에 응답이 없습니다</strong>는 연결은 되었지만 응답이 요청의 시간 초과보다 오래 걸렸다는 뜻입니다. 서버가 느리면 요청의 <strong>설정</strong> 탭에서 <strong>시간 초과</strong>를
늘리세요. <strong>…에 제시간에 연결하지 못했습니다</strong>는 연결 자체가 열리지 않았다는 뜻입니다. 방화벽, VPN, 또는 꺼져 있는 서버가 원인입니다.

</Accordion>
<Accordion title="…이(가) 응답하기 전에 유지 중이던 연결을 닫았습니다">

Echolot은 열려 있는 연결을 재사용합니다. 요청이 나가는 바로 그 순간 서버가 연결 하나를 닫았고 응답이 돌아오지 않았습니다.

두 번 보내도 되는 요청(GET 등 안전하거나 멱등한 메서드, 또는 `Idempotency-Key` 헤더가 있는 요청)은 Echolot이 새 연결로 한 번 자동으로 재시도합니다.
POST 같은 다른 요청은 서버가 이미 요청을 처리했을 수 있으므로 재시도하지 않습니다. 다시 보내기 전에 확인하세요.

</Accordion>
<Accordion title="…에 연결할 수 없습니다 / …이(가) 연결을 재설정했습니다">

<strong>연결할 수 없습니다</strong>는 네트워크에 서버로 가는 경로가 없다는 뜻입니다. Wi-Fi, 네트워크, VPN을 확인하세요. <strong>연결을 재설정했습니다</strong>는 서버나 중간의 무언가가
연결을 끊었다는 뜻이며, 방화벽이거나 프로토콜을 거부하는 서버인 경우가 많습니다(예: HTTPS 포트로 보낸 일반 HTTP).

</Accordion>
<Accordion title="demo.echolot.dev에서 429 Too Many Requests">

[데모 API](/docs/tutorials/demo-api)는 공유되며 주소당 분당 120개 요청으로 제한하고, 크거나 느리거나 스트리밍하는 엔드포인트(내보내기, `bytes`, `delay`,
WebSocket, SSE)는 분당 10개로 제한합니다. `Retry-After` 응답 헤더에 있는 초만큼 기다린 뒤 다시 보내세요. 데모에 대해 반복이 많은 실행을 하면 한도에 금방
도달하므로 반복 횟수를 줄이세요.

</Accordion>
</Accordions>

## TLS와 인증서 [#tls-and-certificates]

<Accordions type="single">
<Accordion title="…의 인증서를 신뢰할 수 없습니다">

서버의 인증서가 자체 서명되었거나, 만료되었거나, Mac이 신뢰하는 기관이 서명하지 않았습니다. 메시지에 어느 쪽인지 표시됩니다.

- 회사나 개발용 인증 기관이라면 검사를 끄는 대신 <strong>작업 공간 설정 › 인증서</strong>에서 그 호스트에 대한 CA 인증서를 추가하세요. [요청 설정](/docs/requests/settings)을
  참조하세요.
- 개발 서버인 경우에만 요청의 <strong>설정</strong> 탭에서 <strong>TLS 인증서 확인</strong>을 끄세요.

</Accordion>
<Accordion title="…의 인증서가 다른 호스트 이름용입니다">

인증서는 유효하지만 다른 호스트를 가리키고 있습니다. 인증서가 발급된 호스트 이름을 사용하거나 서버의 인증서를 고치세요.

</Accordion>
<Accordion title="…에 대한 보안 연결에 실패했습니다(TLS 핸드셰이크)">

서버와의 TLS 핸드셰이크에 실패했습니다. 콜론 뒤의 텍스트는 TLS 라이브러리가 알려 주는 이유입니다. 흔한 원인은 클라이언트 인증서를 요구하는 서버입니다.
<strong>작업 공간 설정 › 인증서</strong>에서 그 호스트에 인증서를 추가하세요.

</Accordion>
<Accordion title="클라이언트 인증서 파일 …이(가) 없습니다 / PEM 인증서가 아닙니다">

인증서 설정이 이동된 파일이나 다른 형식의 파일을 가리키고 있습니다. <strong>작업 공간 설정 › 인증서</strong>에서 파일을 다시 선택하세요. Echolot은 PEM 인증서를
읽습니다.

</Accordion>
</Accordions>

## 프록시 [#proxies]

<Accordions type="single">
<Accordion title="요청이 내 프록시를 거치지 않거나, 거치지 말아야 할 프록시를 거칩니다">

<strong>설정 › 네트워크 › 프록시</strong>가 결정합니다.

| 선택 | 의미 |
| --- | --- |
| <strong>시스템 설정</strong> | 시스템 설정 › 네트워크의 HTTP, HTTPS, SOCKS 프록시와 그 예외. 자동 프록시 구성(PAC)은 사용하지 않습니다. |
| <strong>없음</strong> | 모든 요청이 직접 연결됩니다. |
| <strong>수동</strong> | 직접 입력하는 HTTP, HTTPS, SOCKS5 프록시와 <strong>사용자 이름</strong>, <strong>비밀번호</strong>(키체인에 보관), 프록시를 거치지 않을 호스트를 위한 <strong>직접 연결</strong>. |

작업 공간은 <strong>작업 공간 설정 › 프록시</strong>에서 자체 프록시를 설정할 수 있으며, 앱의 프록시보다 우선합니다. 회사에서 PAC 파일을 사용한다면 그 프록시를
<strong>수동</strong>에 입력하세요. 명령줄 도구는 `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`를 읽습니다.

</Accordion>
<Accordion title="프록시 …에 자격 증명이 필요합니다(407)">

프록시에 로그인해야 합니다. <strong>설정 › 네트워크</strong> 또는 작업 공간의 프록시 설정에서 프록시에 <strong>사용자 이름</strong>과 <strong>비밀번호</strong>를 추가하세요.

</Accordion>
<Accordion title="프록시 …이(가) …에 대한 연결을 거부했습니다 / SOCKS 프록시 …이(가) …에 연결할 수 없습니다">

프록시는 작동하지만 해당 서버에 접속하지 않거나 접속할 수 없습니다. 프록시의 규칙이 막고 있거나, 프록시가 있는 위치에서 서버가 꺼져 있습니다. 서버가 로컬이나
내부 서버라면 <strong>직접 연결</strong>에 추가하세요.

</Accordion>
</Accordions>

## HTTP/3 [#http3]

<Accordions type="single">
<Accordion title="HTTP/3에는 macOS 27 이상이 필요합니다">

HTTP/3은 macOS 27 이상에서 작동합니다. 이전 macOS에서는 요청의 <strong>설정</strong> 탭에서 <strong>HTTP/2</strong> 또는 <strong>자동</strong>을 선택하세요.

</Accordion>
<Accordion title="HTTP/3은 프록시를 거칠 수 없습니다 / 아직 사용자 지정 CA 파일이나 클라이언트 인증서를 사용할 수 없습니다">

Echolot은 HTTP/3을 프록시(브라우저처럼 시스템 프록시 포함), 사용자 지정 CA 파일, 클라이언트 인증서와 함께 보내지 않습니다. 그 요청에는 <strong>HTTP/2</strong> 또는
<strong>자동</strong>을 선택하세요. <strong>자동</strong>에서는 서버가 HTTP/3을 제공하고 방해되는 것이 없을 때에만 Echolot이 저절로 HTTP/3으로 전환하며, QUIC 연결을 열 수 없으면
TCP로 대체합니다.

</Accordion>
</Accordions>

## MCP 서버 [#mcp-servers]

<Accordions type="single">
<Accordion title="로컬(stdio) MCP 서버가 시작되지 않습니다">

서버 검사에서 <strong>서버 시작</strong>이 실패로 표시됩니다.

- <strong>먼저 승인하세요.</strong> Echolot은 MCP 서버 페이지에서 <strong>신뢰하고 확인</strong>으로 승인한 뒤에만 로컬 서버의 명령을 시작합니다. 그때까지 호출은 `Echolot은 “…” MCP
  서버를 시작한 적이 없습니다. MCP 서버 페이지에서 명령을 검토하고 먼저 신뢰하십시오.`라고 표시합니다. 명령, 인수, 환경이 바뀌면 다시 묻습니다.
- <strong>명령을 찾을 수 없습니다.</strong> 해결 방법은 `“npx”이(가) 설치되어 있고 PATH에 있는지 확인하거나 전체 경로를 입력하십시오.`라고 안내합니다. Echolot은 로그인 셸의
  PATH로 서버를 시작하므로, 새 터미널 윈도우에서 작동하는 `npx`, `uvx`, 버전 관리자의 shim은 Echolot에서도 작동합니다. 셸이 대화형으로 하는 일을 거친 뒤에야
  작동하는 명령이라면 전체 경로를 입력하세요(터미널에서 `which npx`로 찾을 수 있습니다).
- <strong>시작했다가 멈춥니다.</strong> 같은 명령을 터미널에서 실행해 이유를 확인하세요. 서버의 오류 출력은 메시지 로그에도 있습니다.

[서버 추가](/docs/mcp-servers/adding-servers)를 참조하세요.

</Accordion>
<Accordion title="…은(는) 로컬 프로그램으로 실행되는 MCP 서버이며 Echolot은 여기서 프로그램을 시작할 수 없습니다">

Mac App Store 에디션을 사용 중이며, 이 에디션은 Mac에서 프로그램을 시작할 수 없습니다. 서버는 작업 공간에 그대로 남아 있습니다. 서버가 HTTP를 제공하면 HTTP로
추가하거나, 명령줄 도구(`echolot mcp check -- <command>`)로 실행하거나, 직접 다운로드 버전을 사용하세요. [에디션](/docs/get-started/editions)을 참조하세요.

</Accordion>
<Accordion title="HTTP MCP 서버가 권한 부여 또는 서버 연결 가능에서 실패합니다">

검사의 해결 안내 줄이 무엇을 할지 알려 줍니다. OAuth를 요구하는 서버는 <strong>로그인</strong>, 토큰을 요구하는 서버는 `Authorization` 헤더, 404라면 올바른 경로(MCP
엔드포인트는 흔히 `/mcp`)입니다.

</Accordion>
</Accordions>

## 파일과 스크립트 [#files-and-scripts]

<Accordions type="single">
<Accordion title="Echolot에 “…”을(를) 읽을 권한이 없습니다">

Mac App Store 에디션에서 Echolot은 사용자가 선택한 뒤에만 작업 공간 밖의 파일을 읽을 수 있습니다. 파일에서 스트리밍하는 본문, 폼 파트, 클라이언트 인증서,
Echolot 밖에서 경로를 적은 `.proto` 파일에서 이런 일이 생깁니다. 실패한 응답에서 <strong>접근 허용…</strong>을 선택하고 파일을 고른 다음 다시 보내세요. Echolot이 이를
기억합니다.

직접 다운로드 버전에서는 이 메시지가 파일 자체의 권한 때문에 읽을 수 없다는 뜻입니다.

</Accordion>
<Accordion title="Echolot이 이 Mac에서 실행한 적 없는 스크립트를 실행합니다">

요청, 요청의 폴더, 또는 작업 공간에 다른 곳에서 온 스크립트가 있습니다. 가져오기, `git pull`, Echolot 밖의 편집 등입니다. 스크립트는 신뢰한 뒤에만 실행됩니다.
<strong>스크립트 검토…</strong>를 선택하고 읽어 본 다음 신뢰하세요. [스크립트와 테스트](/docs/requests/scripts-and-tests)를 참조하세요.

</Accordion>
<Accordion title="요청을 저장할 수 없습니다">

Echolot이 요청의 파일을 기록할 수 없었습니다. 디스크가 가득 찼거나, 폴더가 읽기 전용이거나, 작업 공간이 이동했습니다. <strong>재시도</strong>는 다시 시도하고, <strong>계속 편집</strong>은
편집 내용을 탭에 그대로 두며 탭은 저장될 때까지 열려 있습니다.

</Accordion>
<Accordion title="디스크에서 이 요청이 변경되었습니다">

탭에 저장되지 않은 편집이 있는 동안 다른 앱이나 Git이 파일을 변경했습니다. <strong>디스크 버전 사용</strong>은 편집 내용을 버리고 파일을 불러오고, <strong>내 변경 사항 유지</strong>는
편집 내용을 유지하고 파일에 덮어씁니다.

</Accordion>
<Accordion title="macOS가 키체인 항목에 대한 접근을 요청합니다">

항목이 다른 Echolot 사본, 다른 에디션, 또는 명령줄 도구가 만든 것입니다. macOS는 항목마다 한 번 묻습니다. <strong>항상 허용</strong>을 선택하세요.

</Accordion>
</Accordions>

## 앱과 명령줄 도구 [#the-app-and-the-command-line-tool]

<Accordions type="single">
<Accordion title="이 베타가 만료됨">

직접 다운로드 버전의 릴리스된 베타 빌드는 릴리스 30일 뒤에, 또는 개발자가 빌드를 종료하면 그보다 일찍 만료됩니다. [echolot.dev](https://echolot.dev)에서 최신 버전을
내려받아 이전 버전 위에 설치하세요. 작업 공간은 그대로 열립니다. 이 Mac의 날짜가 잘못된 것 같다는 알림이 뜬다면 시계가 Echolot이 이미 본 날짜보다 하루 넘게
이전이라는 뜻이므로 시스템 설정에서 날짜와 시간을 설정하세요. [설치](/docs/get-started/install#beta-builds-expire)를 참조하세요.

</Accordion>
<Accordion title="echolot: command not found">

명령줄 도구가 아직 PATH에 없습니다. <strong>Echolot › 명령줄 도구 설치…</strong>를 선택한 다음 <strong>새</strong> 터미널 윈도우를 여세요(열려 있는 윈도우는 이전 PATH를 유지합니다). **설정 ›
일반 › 명령줄 도구<strong>에 링크가 있는 위치가 표시됩니다. 경고가 표시되면 링크가 이동된 Echolot 사본을 가리키고 있는 것이므로 </strong>다시 설치**를 선택하세요. App Store
에디션에서는 도구를 따로 설치하세요. [명령줄 도구](/docs/cli)를 참조하세요.

</Accordion>
<Accordion title="명령줄 도구나 CI에서 비밀 값이 비어 있습니다">

키체인이 없으면(Linux, CI, 또는 `ECHOLOT_KEYCHAIN=0`) 도구는 `ECHOLOT_SECRET_<NAME>`이라는 환경 변수에서 비밀 값을 읽습니다. 예를 들어 비밀 변수
`password`에는 `ECHOLOT_SECRET_PASSWORD`입니다. CI의 비밀 값 설정에서 지정하세요. [CI](/docs/cli/ci)를 참조하세요.

</Accordion>
<Accordion title="Echolot이 …에 저장 공간을 만들 수 없습니다">

Echolot이 저장 폴더를 만들 수 없었으며, 보통 여유 공간이나 권한이 부족해서입니다. Echolot을 다시 시작할 때까지 응답은 임시 폴더에 보관됩니다. 공간을 확보하거나
폴더의 권한을 고친 다음(<strong>설정 › 정보 › 응답 및 기록 › Finder에서 보기</strong>로 위치를 확인할 수 있습니다) 다시 시작하세요.

</Accordion>
</Accordions>

## 그래도 해결되지 않으면 [#still-stuck]

<strong>도움말 › 버그 신고</strong>는 Echolot과 macOS 버전이 채워진 새 이슈를 GitHub에서 엽니다. Echolot이 충돌했다면 그 보고서를 첨부하세요. 
<strong>설정 › 개인정보 보호 › 충돌 보고서 수집</strong>(기본값 켜짐)은 보고서를 이 Mac에 보관하며, <strong>Finder에서 보기</strong>로 폴더를 엽니다.