Claude Code claude rc 404 에러 CCR v2 워커 등록 실패 해결법

by

Claude Code Remote Control CCR v2 워커 등록 404 에러, 원인과 해결법

AWS Lightsail 같은 원격 서버에서 claude remote-control(축약형 claude rc)을 실행하다 보면, 화면에는 분명 Connected 상태가 떠 있는데도 로그 맨 위에 알 수 없는 에러 메시지가 함께 찍히는 경우가 있습니다.

[00:20:32] Error: CCR v2 worker registration failed for session cse_01VU2bmHb7HkdBxwLUfJfemv: Request failed with status code 404
[00:20:34] Environment preserved. Restart `claude remote-control` to reconnect existing sessions.
·✔︎· Connected · today-bullstocks
    Capacity: 0/32 · New sessions will be created in an isolated worktree

겉보기엔 정상적으로 연결된 것 같아서 그냥 넘기기 쉽지만, 이 에러는 나중에 모바일 앱이나 claude.ai/code에서 새 세션을 만들 때 예상치 못한 실패로 이어질 수 있는 “조용한 실패(silent failure)” 패턴입니다. 이번 글에서는 이 에러가 왜 발생하는지, 그리고 어떻게 해결하면 되는지 정리합니다.

왜 404 에러가 발생할까

claude remote-control은 기본적으로 서버를 시작할 때 세션 하나를 미리 생성(pre-create) 해두는 옵션이 켜져 있습니다. 이 사전 생성 세션이 CCR(Claude Code Remote) v2 워커로 등록되는 과정에서 요청이 404로 실패하면서 크래시가 발생하는 것입니다.

문제는 이 크래시가 remote-control 서버 자체의 실패는 아니라는 점입니다. 서버는 정상적으로 기동되고 QR 코드나 접속 URL도 정상 출력되기 때문에, 화면상으로는 Connected로 보입니다. 하지만 실제로는 미리 만들어 둔 세션 하나가 죽은 상태로 남아 있고, 이 과정에서 생성된 워크트리(worktree) 디렉토리가 정리되지 않고 잔재로 남을 수 있습니다.

이 잔재가 남아 있으면, 이후 모바일 앱 등에서 새 세션을 spawn할 때 .claude/worktrees 디렉토리가 이미 존재한다는 이유로 EEXIST 에러가 발생하며 세션 생성 자체가 막힐 수 있습니다. 즉 지금 당장은 문제가 없어 보여도, 누적되면 원격 접속 워크플로우 전체가 막히는 상황으로 이어질 수 있는 것입니다.

해결 방법 1: 사전 세션 생성 자체를 끄기

가장 근본적인 대응은 시작 시 세션을 미리 만들지 않도록 옵션을 끄는 것입니다.

claude remote-control --spawn same-dir --no-create-session-in-dir

--no-create-session-in-dir 옵션을 붙이면 서버가 시작할 때 세션을 자동으로 미리 만들지 않기 때문에, 애초에 404 크래시가 발생할 여지가 없어집니다. 재시작 후에는 Capacity: 0/32로 시작하는 게 정상이며, 실제로 접속해서 세션을 만들 때 정상적으로 카운트가 올라가는지 확인하면 됩니다.

해결 방법 2: –spawn 모드 선택하기

--spawn 옵션은 새 세션이 어떤 방식으로 생성될지를 결정합니다.

  • --spawn worktree: 세션마다 별도의 git 워크트리를 생성합니다. 여러 세션이 동시에 같은 파일을 건드릴 걱정 없이 독립적으로 작업할 수 있어 팀 협업에 유리하지만, 워크트리 관리 부담이 생깁니다.
  • --spawn same-dir: 모든 세션이 같은 디렉토리를 공유합니다. 혼자 여러 기기(PC, 모바일)로 오가며 하나의 작업을 이어서 할 때는 워크트리를 따로 만들 필요가 없어 더 단순합니다. 다만 여러 세션이 동시에 같은 파일을 수정하면 충돌할 수 있다는 점은 유의해야 합니다.

솔로 개발자가 하나의 프로젝트를 PC와 모바일을 오가며 이어서 작업하는 워크플로우라면, 굳이 워크트리를 분리할 이유가 없기 때문에 --spawn same-dir 쪽이 더 실용적입니다.

해결 방법 3: 이미 남아있는 워크트리 잔재 정리

혹시 이미 여러 번 크래시를 겪었다면, 잔재가 남아있는지 먼저 확인하는 것이 안전합니다.

git worktree list

bridge-cse_... 형태의 이름으로 시작하는 항목이 보인다면 아래처럼 정리합니다.

git worktree remove --force .claude/worktrees/bridge-cse_xxxxx
git worktree prune

명령이 실패하거나 애매하다면, 디렉토리를 통째로 지우고 다시 시작하는 편이 더 확실합니다.

rm -rf .claude/worktrees
claude remote-control --spawn same-dir --no-create-session-in-dir

재발 방지를 위한 alias 설정

매번 옵션을 다 타이핑하기보다, ~/.bashrc에 alias를 하나 걸어두면 편합니다.

alias claude-rc='claude remote-control --spawn same-dir --no-create-session-in-dir'

이렇게 해두면 claude-rc 한 줄로 항상 같은 옵션 조합으로 원격 제어 서버를 띄울 수 있어, 같은 에러를 반복해서 마주칠 일이 줄어듭니다.

정리

  • CCR v2 worker registration failed ... 404 에러는 remote-control 서버 자체의 실패가 아니라, 시작 시 자동으로 미리 만들어지는 세션 하나가 등록에 실패하면서 나는 에러다.
  • 화면에 Connected가 떠 있어도 안심할 수 없으며, 워크트리 잔재가 쌓이면 이후 세션 생성이 막힐 수 있다.
  • --no-create-session-in-dir 옵션으로 사전 생성 자체를 끄는 것이 근본적인 해결책이다.
  • 혼자 작업하는 환경이라면 --spawn same-dir로 워크트리 분리 없이 단순하게 운영할 수 있다.
  • 이미 잔재가 있다면 git worktree list로 확인 후 git worktree remove 또는 디렉토리 삭제로 정리한다.

AWS Lightsail에서 tmux로 Claude Code를 상시 구동하며 모바일로 이어서 작업하는 분들이라면, 위 옵션 조합을 기본값으로 alias에 걸어두는 것을 추천합니다.

Leave a Comment