문제 해결
"spawn tmux ENOENT"
tmux가 설치되지 않았거나 PATH에 없습니다. Termbridge은 이 오류를 표시하지만 현재 터미널을 제공하지 않은 채 계속 실행됩니다(#4). Ctrl+C를 누르고 tmux를 설치한 다음 다시 시작하세요.
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt install tmux
"spawn cloudflared ENOENT"
Cloudflare의 터널 클라이언트가 설치되지 않았거나 PATH에 없습니다. 터널 모드에서만 필요하며, --no-tunnel 및 Daytona 직접 모드에는 cloudflared이 필요하지 않습니다.
# macOS
brew install cloudflared
Linux의 경우 cloudflare.com/downloads에서 다운로드하세요.
터널이 시작되지 않음
다음 항목을 확인하세요(직접 샌드박스 모드를 사용하는 경우에는 건너뛰세요):
- cloudflared이 작동하는지 확인하세요:
cloudflared --version https://trycloudflare.com에 연결할 수 있는지 확인하세요- 방화벽이 나가는 연결을 차단하는지 확인하세요
터널 시작에 실패하면 Termbridge는 오류를 표시하고 서버를 중지한 뒤 상태 코드 1로 종료합니다. 로컬 전용 모드로 전환하지 않으며, 기본적으로 서버는 127.0.0.1에서만 수신하므로 네트워크의 다른 기기에서도 접속할 수 없습니다. 해당 실행에서 생성한 tmux 세션은 계속 실행됩니다(#4).
Cloudflare 터널 없이 Termbridge를 사용하려면 자체 리버스 프록시 또는 터널 뒤에서 실행하세요(--no-tunnel --public-url <url> 사용).
trycloudflare에서 표시되는 "429 Too Many Requests"
Cloudflare는 계정 없는 터널의 요청 수를 제한합니다. 429 Too Many Requests와 같은 오류가 표시되면 다음을 시도하세요:
- 몇 분 기다린 뒤 다시 시도하세요
- 오래된
cloudflared프로세스가 계속 실행 중인지 확인하세요 - 자주 사용하는 경우 이름이 지정된 터널 토큰을 사용하세요(권장)
빈 화면 또는 "터미널을 불러올 수 없음"
브라우저에 유효한 세션 쿠키가 없으면 보통 이 문제가 발생합니다. 예를 들어 공유 링크를 교환하지 않고 열었거나 터널 URL가 변경된 경우입니다:
- 로컬 서버가 계속 실행 중인지 확인하세요
- 브라우저 콘솔에서 401/403 오류를 확인하세요
- Termbridge를 다시 시작해 새로운 URL 및 QR 코드를 받으세요
터미널에 출력이 없음
tmux 세션이 실행 중이 아닐 수 있습니다:
# Check if sessions exist
tmux ls
세션이 표시되지만 터미널이 비어 있다면 다음을 시도하세요:
- 페이지 새로고침
- 셸이
TERM=xterm-256color를 지원하는지 확인
QR 코드를 스캔했지만 페이지가 비어 있음
QR 코드에는 일회용 토큰이 들어 있습니다. 한 번만 사용할 수 있으며 Termbridge가 시작된 뒤 90초 이내에만 작동합니다. 이미 사용했거나 만료된 링크를 열면 invalid token가 반환됩니다.
해결 방법: Termbridge를 다시 시작해 새로운 QR 코드를 생성한 다음 바로 스캔하세요.
node-pty에서 spawn-helper 관련 오류가 표시됨
Termbridge는 이 문제를 자동으로 해결하려고 시도합니다. 권한 오류가 표시되면 다음을 확인하세요:
chmod +x node_modules/node-pty/prebuilds/**/spawn-helper
여전히 해결되지 않았나요?
github.com/inline0/termbridge에서 다음 정보와 함께 이슈를 등록하세요:
- 운영체제 및 Node.js 버전
- 오류 메시지
- 재현 단계