Clash 구독 업데이트 실패·파싱 오류 해결 방법과 점검 목록

1. 먼저 오류를 기록하고 실패 단계 파악하기

구독 업데이트는 한 번에 끝나는 작업이 아닙니다. 클라이언트가 먼저 구독 주소에 요청을 보내고, 응답 내용을 파싱한 뒤, 설정과 코어의 호환성을 확인합니다. 마지막으로 노드와 프록시 그룹, 외부 리소스를 불러옵니다. 화면에 표시되는 ‘업데이트 실패’는 이 중 어느 단계에서든 발생할 수 있습니다. 클라이언트를 반복해서 재설치하기보다 먼저 실패한 단계를 찾는 편이 효과적입니다.

클라이언트의 ‘구독’ 또는 ‘프로필’ 페이지에서 오류가 난 설정 카드를 찾아 마지막 업데이트 시간과 설정 이름을 기록합니다.
‘로그’를 열어 기존 기록을 지우거나 현재 시간을 확인한 다음, 설정 카드로 돌아와 ‘업데이트’를 한 번만 누릅니다. 클라이언트에 따라 버튼 이름이 ‘새로고침’ 또는 ‘구독 업데이트’일 수 있습니다.
로그로 돌아가 이번 작업 이후 가장 먼저 나타난 오류를 찾습니다. 오류 유형, HTTP 상태 코드, 줄 번호와 필드 이름을 기록하고 마지막 줄의 ‘실패’ 메시지만 캡처하지 마세요.

로그 또는 화면에 표시된 내용	주로 해당하는 단계	우선 확인 항목
`no such host`	도메인 확인	구독 도메인, 현재 네트워크의 DNS
`timeout`、`deadline exceeded`	연결 또는 응답 대기	요청 경로, 네트워크, 서버 응답
HTTP 401、403、404、429	서버에서 거부 또는 오류 응답	링크 권한, 유효 기간, 요청 빈도
`yaml: line 12`	응답 내용 파싱	실제 응답 본문, 12번째 줄 부근의 들여쓰기
`unsupported proxy type`	설정 호환성 확인	프로토콜 유형과 현재 실행 중인 코어
업데이트는 완료됐지만 노드가 없음	설정 로드 또는 노드 provider 업데이트	활성 설정, 필터 조건, providers 로그

2. 링크 점검: 구독 주소를 복사했는지 확인하기

1. 서비스 대시보드에서 Clash 형식 링크 다시 복사하기

구독 제공업체의 계정 대시보드에서 ‘구독’ → ‘구독 주소 복사’를 찾아 Clash 또는 Mihomo 형식이 명시된 항목을 선택하세요. 계정 홈 주소, 요금제 구매 페이지, QR 코드 이미지 주소는 설정 URL로 사용할 수 없습니다. QR 코드에는 클라이언트를 실행하는 가져오기 명령이 들어 있을 수도 있으므로, 대시보드에 표시된 원본 HTTPS 구독 주소를 우선 사용하세요.

주소가 완전한 https://로 시작하는지, 끝에 공백이나 줄바꿈 또는 메신저가 덧붙인 문장 부호가 들어 있지 않은지 확인하세요.
? 뒤의 쿼리 매개변수는 그대로 두세요. 토큰은 보통 매개변수나 경로에 포함되며, 삭제하면 401 또는 403 오류가 발생할 수 있습니다.
링크를 재발급한 적이 있다면 기존 주소는 즉시 만료될 수 있습니다. 기존 설정의 구독 URL을 수정한 다음 업데이트하고, 이름이 같은 이전 설정을 실수로 선택하지 않도록 주의하세요.
계정 만료일과 트래픽 사용 상태를 확인하세요. 제공업체는 상태 코드나 안내 문구로 이용 정지 사유를 표시할 수 있으므로 계정 대시보드에서 확인하는 것이 정확합니다.

2. 상태 코드와 응답 내용을 함께 확인하기

401은 보통 유효한 인증 정보가 필요하다는 뜻입니다. 403은 접근 정책, 토큰 권한 또는 보안 차단 때문일 수 있고, 404는 경로가 변경됐거나 서버에서 유효하지 않은 리소스를 숨기는 경우일 수 있습니다. 429가 표시되면 연속으로 새로고침하지 말고 서버 안내에 따라 기다리세요. 응답에 Retry-After가 있으면 해당 값을 따르세요. 5xx 오류는 보통 제공업체가 서버를 확인해야 하지만, 중간 게이트웨이가 오류 페이지를 반환했는지도 살펴보세요.

HTTP 200은 요청이 성공 응답을 받았다는 뜻일 뿐, 본문이 반드시 Clash 설정이라는 의미는 아닙니다. 본문이 <!DOCTYPE html>로 시작하거나 로그인, 인증 코드, 요금제 안내가 들어 있다면 파서가 받은 것은 웹페이지입니다. 이 경우 YAML 들여쓰기를 고쳐도 해결되지 않으므로 링크나 서버 응답부터 확인해야 합니다.

3. 네트워크 점검: 직접 연결·프록시·DNS를 따로 테스트하기

브라우저에서 계정 대시보드가 열린다고 해서 클라이언트가 구독을 가져올 수 있는 것은 아닙니다. 대시보드와 구독은 서로 다른 도메인을 사용할 수 있고, 브라우저와 클라이언트 UI 프로세스, 코어가 서로 다른 네트워크 경로를 이용할 수도 있습니다. 다른 설정은 그대로 둔 채 한 번에 한 항목씩 비교해 보세요.

시스템 시간을 확인하세요. 시스템의 ‘날짜 및 시간’에서 자동 시간 설정을 켭니다. 날짜가 크게 어긋나 있으면 TLS 인증서 유효성 검사가 실패할 수 있습니다.
구독 가져오기 방식을 확인하세요. 설정 카드 메뉴나 구독 설정에서 ‘프록시를 통해 업데이트’, ‘업데이트 방식’과 같은 항목을 찾아보세요. 해당 기능이 있다면 직접 연결과 현재 사용 가능한 프록시를 통한 업데이트를 각각 테스트하고 결과를 기록하세요.
네트워크를 바꿔 다시 테스트하세요. 사용이 허용된 네트워크에서 컴퓨터를 잠시 모바일 핫스팟에 연결한 뒤 같은 구독을 업데이트합니다. 한 네트워크에서만 실패한다면 해당 네트워크의 DNS 확인, 인증 또는 접근 제한부터 점검하세요.
로컬 프록시 포트를 확인하세요. 클라이언트 ‘설정’에서 포트 정보를 열고 HTTP 또는 mixed 포트가 실제로 수신 중인지 확인하세요. 인터넷에서 찾은 기본값을 그대로 사용하면 안 됩니다.

로컬 명령으로 응답 오류와 연결 오류 구분하기

명령줄 사용에 익숙하다면 로컬에서 두 가지 요청 경로를 비교할 수 있습니다. 아래 예시는 구독 주소를 대화형으로 입력하므로 전체 링크가 명령 기록에 남지 않습니다. 프록시 포트 7890은 예시일 뿐이므로 클라이언트에 표시된 HTTP 또는 mixed 포트로 바꿔야 합니다. 이 명령은 일반적인 Bash 및 Zsh 환경에서 사용할 수 있으며, 응답은 현재 디렉터리의 로컬 파일에 저장됩니다.

printf '구독 주소를 입력하세요: '
IFS= read -r SUB_URL
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 --location \
  --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

여기서는 연결 시간 초과를 10초, 전체 대기 시간을 30초로 설정해 비교 가능한 진단 조건을 만들었습니다. 모든 클라이언트에 일괄 적용할 권장값은 아닙니다. 파일에 노드 비밀번호와 토큰이 포함될 수 있으므로 확인 후 안전하게 삭제하고 공개 저장소에 동기화하지 마세요. 명령 테스트는 클라이언트의 User-Agent, 요청 헤더와 코어 라우팅을 완전히 재현하지 못합니다. 결과가 다르면 한쪽에 문제가 있다고 단정하지 말고 차이를 단서로 활용하세요.

로그에 no such host가 표시되면 먼저 시스템에서 구독 도메인을 확인할 수 있는지 점검하세요. 구독 요청이 아직 코어에 도달하지 않았다면 YAML의 dns:를 수정해도 적용되지 않을 수 있습니다. TUN은 일부 네트워크 트래픽의 처리 방식을 바꾸지만 만료된 토큰이나 형식 오류를 해결하지는 않습니다. 점검하는 동안 TUN, DNS, 규칙 모드를 동시에 바꾸지 마세요.

4. 형식 점검: YAML 오류와 코어 비호환 문제를 따로 해결하기

전체 설정인지 노드 목록인지 먼저 확인하기

일반적인 Clash 전체 설정에는 최상위 필드로 proxies, proxy-groups, rules 등이 포함됩니다. proxy-providers를 통해 외부 노드를 참조할 수도 있으므로, 설정에 노드가 직접 표시되지 않는다는 이유만으로 내용이 비어 있다고 판단하면 안 됩니다. 반대로 한 줄씩 나열된 프로토콜 공유 링크, 범용 Base64 구독, provider 전용 노드 목록은 바로 활성화할 수 있는 전체 설정과 다릅니다.

먼저 클라이언트의 가져오기 기능이 지원하는 형식을 확인한 다음 구독 제공업체의 출력 형식과 비교하세요. 클라이언트가 자동 변환을 지원한다고 명시하지 않았다면 호환되는 형식을 선택해야 합니다. 변환이 필요하면 제공업체가 공식 지원하는 방법이나 신뢰할 수 있는 로컬 처리 절차를 우선 사용하고, 낯선 온라인 서비스에 접근 토큰을 넘기지 마세요.

오류 줄 번호를 기준으로 들여쓰기와 데이터 유형 확인하기

로그의 줄 번호는 점검을 시작할 위치이지, 오류가 반드시 그 줄에서 발생했다는 뜻은 아닙니다. 예를 들어 12번째 줄에 오류가 표시되어도 원인은 11번째 줄에서 따옴표를 빠뜨린 것일 수 있습니다. YAML 들여쓰기에는 탭 대신 공백을 사용하세요. 콜론 뒤에는 올바른 구분이 필요하고 목록 항목 앞에는 하이픈을 붙여야 합니다. 아래는 구조를 보여 주는 일부 예시이며, 그대로는 완전한 구독 설정으로 가져올 수 없습니다.

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - "노드 A"
rules:
  - "MATCH,수동 선택"

mapping values are not allowed: 콜론과 들여쓰기를 확인하고 앞 줄에서 따옴표가 빠지지 않았는지 살펴보세요.
cannot unmarshal: 필드에 문자열, 목록, 매핑 중 어떤 유형이 필요한지 확인하세요. 공백만 조정해서는 해결되지 않습니다.
프록시 그룹이 존재하지 않는 항목을 참조한다는 메시지가 표시되면 노드 이름과 그룹 이름의 대소문자, 공백, 기호가 완전히 일치하는지 확인하세요.
원격 구독을 다운로드한 뒤 생성된 캐시 파일만 수정하면 다음 업데이트에서 변경 사항이 덮어써질 수 있습니다. 원본 설정이나 클라이언트가 지원하는 오버라이드 방식으로 수정하세요.

실제로 실행 중인 코어 확인하기

‘설정’ → ‘정보’ 또는 클라이언트의 코어 정보 페이지에서 클라이언트 버전과 코어 버전을 각각 기록하세요. 두 버전은 서로 다릅니다. Clash Meta는 현재 보통 mihomo라고 부릅니다. 브랜치와 버전에 따라 지원하는 프로토콜과 필드가 다를 수 있습니다. unsupported proxy type 오류가 표시되면 필드를 무조건 삭제해 강제로 불러오지 말고, 오류에 나온 프로토콜의 호환성을 확인하세요.

클라이언트나 코어를 바꾸기 전에 설정을 백업한 뒤 신뢰할 수 있는 배포 경로에서 호환되는 버전을 받으세요. 현재 기기에서 필요한 코어를 사용할 수 없다면 제공업체에 호환되는 출력 형식이 있는지 문의하세요. UI 프로그램만 업데이트해도 실행 중인 코어가 바뀌는 것은 아닙니다. 업데이트 후 코어 정보 페이지에서 다시 확인하세요.

5. 업데이트는 성공했지만 노드 목록이 비어 있음: 활성 설정과 providers 확인하기

‘구독 업데이트 완료’는 기본 설정을 다운로드했다는 뜻일 수 있으며, 기본 설정에서 참조하는 모든 리소스를 가져왔다는 의미는 아닙니다. 특히 proxy-providers를 사용하면 노드 파일을 별도로 요청하므로 주소, 캐시, 업데이트 주기가 각각 다를 수 있습니다.

현재 활성화된 설정을 확인하세요. ‘설정’ 또는 ‘구독’ 페이지로 돌아가 방금 업데이트한 설정에 선택 표시가 있는지 확인합니다. 설정 A를 업데이트했다고 해서 설정 B에서 A로 전환된 것은 아닙니다.
전체 프록시 그룹을 살펴보세요. ‘프록시’ 페이지를 열고 노드를 실제로 참조하는 그룹을 펼칩니다. 일부 홈 화면에는 현재 선택된 정책만 표시되고 전체 노드는 나오지 않습니다.
provider 상태를 확인하세요. 클라이언트에 ‘프록시 제공자’ 페이지가 있다면 노드 수, 업데이트 시간과 오류를 확인합니다. 별도 페이지가 없다면 로그에서 provider 이름과 다운로드 오류를 찾으세요.
필터 표현식을 확인하세요. 정규식 필터가 모든 노드를 제외했을 수 있습니다. 유일하게 작동하는 설정을 바로 수정하지 말고 백업 복사본이나 로컬 오버라이드에서 관련 필터를 제거해 테스트하세요.
프록시 그룹 참조를 확인하세요. provider 이름은 프록시 그룹의 use에 지정된 이름과 일치해야 합니다. provider에 노드가 있어도 프록시 그룹에서 참조하지 않으면 화면에 원하는 노드가 보이지 않을 수 있습니다.

로그에 규칙 provider인 rule-providers 업데이트 실패가 표시되면 규칙 파일의 주소와 형식을 별도로 확인하세요. 규칙 리소스 오류가 노드 구독이 비어 있다는 뜻은 아니지만 설정 로드나 트래픽 분배에 영향을 줄 수 있으므로 구체적인 로그를 기준으로 판단하세요.

6. 복구 확인 및 문의 시 준비할 정보

수정한 뒤 ‘업데이트, 로드, 연결’ 세 단계를 확인하세요. 먼저 수동으로 한 번 업데이트하고 로그에 새로운 구독 요청 오류가 없는지 확인합니다. 다음으로 대상 설정을 활성화해 노드 또는 provider 수가 예상과 맞는지 확인하세요. 마지막으로 노드를 선택하고 평소 이용하는 서비스에 연결해 실제 출구 IP와 규칙 일치 결과를 연결 페이지에서 확인합니다.

업데이트 확인: 작업 시간을 기록하고 설정의 마지막 업데이트 시간이 바뀌었는지 확인하세요. provider를 사용한다면 provider 업데이트 시간도 확인합니다.
로드 확인: YAML, 프로토콜 유형 또는 프록시 그룹 참조 오류가 없는지, 대상 설정이 실제로 활성화되어 있는지 확인하세요.
연결 확인: 시스템 프록시 또는 필요에 따라 활성화한 TUN이 의도한 상태인지 확인하세요. 트래픽이 프록시를 통하지 않은 것을 구독 오류로 오해하지 않도록 주의하세요.
설정 유지 확인: 적절한 자동 업데이트 일정을 복원하고 다음 업데이트 후에도 필요한 로컬 오버라이드가 유지되는지 확인하세요.

계속 실패한다면 다음 정보를 제공하세요

구독 제공업체나 클라이언트 유지관리자에게 문의할 때 운영체제, 클라이언트 버전, 코어 이름과 버전, 실패 시간과 시간대, 민감 정보를 가린 전체 오류 내용, 직접 연결과 프록시 업데이트의 비교 결과를 함께 보내세요. 응답이 HTTP 오류인지, 웹페이지인지, YAML 파싱 오류인지 설명하면 불필요한 추가 문의를 줄일 수 있습니다.

설정 일부를 전달해야 한다면 재현에 필요한 필드만 남기고 서버 주소, 비밀번호, 접근 토큰은 다른 값으로 바꾸세요. 전체 구독 링크가 유출됐다면 계정 대시보드에서 링크를 재발급한 뒤 클라이언트에 저장된 주소도 업데이트하세요. 이후 전체 매뉴얼의 구독 설정 섹션을 참고해 설정을 정리하고, 원격 구독·노드 provider·로컬 오버라이드를 같은 계층에서 처리하지 않도록 하세요.