# 문제 해결

## "spawn tmux ENOENT"

tmux가 설치되지 않았거나 PATH에 없습니다. Termbridge은 이 오류를 표시하지만 현재 터미널을 제공하지 않은 채 계속 실행됩니다([#4](https://github.com/inline0/termbridge/issues/4)). `Ctrl+C`를 누르고 tmux를 설치한 다음 다시 시작하세요.

```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

## "spawn cloudflared ENOENT"

Cloudflare의 터널 클라이언트가 설치되지 않았거나 PATH에 없습니다. 터널 모드에서만 필요하며, `--no-tunnel` 및 Daytona 직접 모드에는 cloudflared이 필요하지 않습니다.

```bash
# macOS
brew install cloudflared
```

Linux의 경우 [cloudflare.com/downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)에서 다운로드하세요.

## 터널이 시작되지 않음

다음 항목을 확인하세요(직접 샌드박스 모드를 사용하는 경우에는 건너뛰세요):

1. cloudflared이 작동하는지 확인하세요: `cloudflared --version`
2. `https://trycloudflare.com`에 연결할 수 있는지 확인하세요
3. 방화벽이 나가는 연결을 차단하는지 확인하세요

터널 시작에 실패하면 Termbridge는 오류를 표시하고 서버를 중지한 뒤 상태 코드 1로 종료합니다. 로컬 전용 모드로 전환하지 않으며, 기본적으로 서버는 `127.0.0.1`에서만 수신하므로 네트워크의 다른 기기에서도 접속할 수 없습니다. 해당 실행에서 생성한 tmux 세션은 계속 실행됩니다([#4](https://github.com/inline0/termbridge/issues/4)).

Cloudflare 터널 없이 Termbridge를 사용하려면 자체 리버스 프록시 또는 터널 뒤에서 실행하세요(`--no-tunnel --public-url <url>` 사용).

## trycloudflare에서 표시되는 "429 Too Many Requests"

Cloudflare는 계정 없는 터널의 요청 수를 제한합니다. `429 Too Many Requests`와 같은 오류가 표시되면 다음을 시도하세요:

1. 몇 분 기다린 뒤 다시 시도하세요
2. 오래된 `cloudflared` 프로세스가 계속 실행 중인지 확인하세요
3. 자주 사용하는 경우 이름이 지정된 터널 토큰을 사용하세요(권장)

## 빈 화면 또는 "터미널을 불러올 수 없음"

브라우저에 유효한 세션 쿠키가 없으면 보통 이 문제가 발생합니다. 예를 들어 공유 링크를 교환하지 않고 열었거나 터널 URL가 변경된 경우입니다:

1. 로컬 서버가 계속 실행 중인지 확인하세요
2. 브라우저 콘솔에서 401/403 오류를 확인하세요
3. Termbridge를 다시 시작해 새로운 URL 및 QR 코드를 받으세요

## 터미널에 출력이 없음

tmux 세션이 실행 중이 아닐 수 있습니다:

```bash
# Check if sessions exist
tmux ls
```

세션이 표시되지만 터미널이 비어 있다면 다음을 시도하세요:
- 페이지 새로고침
- 셸이 `TERM=xterm-256color`를 지원하는지 확인

## QR 코드를 스캔했지만 페이지가 비어 있음

QR 코드에는 일회용 토큰이 들어 있습니다. 한 번만 사용할 수 있으며 Termbridge가 시작된 뒤 90초 이내에만 작동합니다. 이미 사용했거나 만료된 링크를 열면 `invalid token`가 반환됩니다.

해결 방법: Termbridge를 다시 시작해 새로운 QR 코드를 생성한 다음 바로 스캔하세요.

## node-pty에서 spawn-helper 관련 오류가 표시됨

Termbridge는 이 문제를 자동으로 해결하려고 시도합니다. 권한 오류가 표시되면 다음을 확인하세요:

```bash
chmod +x node_modules/node-pty/prebuilds/**/spawn-helper
```

## 여전히 해결되지 않았나요?

[github.com/inline0/termbridge](https://github.com/inline0/termbridge/issues)에서 다음 정보와 함께 이슈를 등록하세요:
- 운영체제 및 Node.js 버전
- 오류 메시지
- 재현 단계