Clash 구독 업데이트 실패·파싱 오류 원인과 단계별 해결 방법

구독 다운로드, 설정 파싱, 커널 로드를 구분하세요

‘업데이트 실패’가 곧 노드 연결 실패를 뜻하지는 않습니다. 구독 업데이트는 일반적으로 클라이언트가 구독 주소에 요청을 보내고, 받은 텍스트에서 설정을 파싱한 다음, 생성된 설정을 커널에서 검사하거나 불러오는 세 단계로 진행됩니다. 어느 단계에서든 실패하면 화면에 오류가 표시될 수 있습니다. 먼저 업데이트 버튼을 연이어 누르기보다 전체 오류 메시지를 보관하세요.

데스크톱 클라이언트는 보통 ‘구독’ 또는 ‘설정’ 화면에서 업데이트를 시작하고, ‘로그’ 화면에서 세부 내용을 확인할 수 있습니다. 메뉴 이름은 클라이언트 버전에 따라 다를 수 있습니다. 클라이언트 버전, 커널 이름과 버전, 실패 시각, 수동 업데이트인지 자동 업데이트인지 기록해 두세요. Clash와 Clash Meta(현 mihomo)는 지원하는 설정 기능이 완전히 같지 않으므로 앱 이름만으로 호환성을 판단하기 어렵습니다.

대표 오류 메시지	우선 점검할 단계	다음 조치
`no such host`	도메인 확인	구독 호스트 이름과 DNS 응답 확인
`timeout`、`connection refused`	연결 또는 응답 대기	네트워크 경로, 프록시 포트, 서비스 상태 확인
HTTP 401、403、429	서버 응답	인증, 접근 제한, 요청 빈도 확인
`yaml: line 12`	텍스트 파싱	응답 본문과 12행 전후 내용 확인
`proxy not found`	설정 참조 검사	정책 그룹, 노드, 규칙에서 참조하는 이름 확인

구독 링크 만료, 인증 실패, 서버 제한

관리 페이지가 아닌 구독 주소인지 확인하세요

구독 주소에는 보통 토큰, 쿼리 매개변수 또는 전용 경로가 포함됩니다. 계정 관리 페이지, 로그인 페이지, QR 코드 이미지 주소는 구독 주소로 사용할 수 없습니다. 제공업체 페이지에서 ‘Clash’ 또는 ‘mihomo’ 형식의 구독 링크를 다시 복사하고, 앞뒤에 공백·줄바꿈·한국어 인용 부호가 붙지 않았는지 확인하세요. 웹페이지 소스에서 복사했다면 &가 HTML에서 이스케이프된 구분자일 수 있으며, 원래 링크에 포함된 문자가 아닐 수 있습니다.

401: 일반적으로 인증 문제입니다. 토큰이 재발급되었는지, 계정이 만료되었는지 확인하세요. 정확한 의미는 제공업체 안내를 따르세요.
403: 접근 정책, 접속 IP, User-Agent 또는 계정 권한 제한일 수 있습니다. 곧바로 ‘링크 만료’라고 단정하지 마세요.
404: API 경로가 변경되었는지, 링크가 잘리지 않았는지, 기존 구독이 취소되었는지 확인하세요.
429: 반복 업데이트를 중단하고 응답의 Retry-After 값이나 제공업체 안내에 따라 기다리세요. 여러 기기에서 자동 새로고침을 설정하면 제한에 걸릴 수 있습니다.
502, 503, 504: 우선 서버 또는 중간 게이트웨이 문제를 의심하세요. 발생 시각을 기록하고 잠시 후 다시 시도하세요.

브라우저에서 열려도 클라이언트가 같은 내용을 받았다는 뜻은 아닙니다

브라우저는 로그인 쿠키를 보내거나 웹 인증을 통과한 뒤에야 내용을 표시할 수 있지만, 클라이언트는 이런 세션을 공유하지 않는 경우가 많습니다. HTTP 상태 코드가 200이어도 본문이 로그인 페이지, CAPTCHA 화면 또는 ‘트래픽 소진’ 안내일 수 있습니다. 상태 코드뿐 아니라 최종 응답 내용도 확인하세요. 구독 주소를 공개 온라인 검사기에 입력하지 마세요. 토큰만으로도 계정에 연결된 노드 정보를 조회할 수 있는 경우가 많습니다.

로컬 네트워크 차단: DNS, TLS, 프록시 경로 점검

구독 다운로드에 사용되는 네트워크 경로와 노드 연결 경로는 다를 수 있습니다. 일부 클라이언트는 그래픽 인터페이스에서 설정을 다운로드하고, 다른 클라이언트는 별도 구성 요소가 처리합니다. 시스템 프록시, TUN, 클라이언트의 ‘프록시를 통해 업데이트’ 설정에 따라 결과가 달라질 수 있습니다. 브라우저에서 사이트에 접속할 수 있다는 사실은 브라우저의 현재 경로가 작동한다는 것만 보여 줍니다.

시스템 시간을 확인하세요. 날짜, 시간대 또는 시계가 크게 틀리면 TLS 인증서 검증에 실패할 수 있습니다. 먼저 자동 시간 동기화를 켠 다음 한 번 더 시도하세요.
도메인 확인. Windows에서는 nslookup 뒤에 구독 호스트 이름을 입력해 실행하세요. macOS와 Linux에서는 dig를 사용할 수 있습니다. 호스트 이름만 입력하고 토큰 경로는 포함하지 마세요.
두 네트워크를 비교하세요. 같은 클라이언트와 설정을 사용해 휴대폰 핫스팟으로 접속해 보세요. 핫스팟에서는 성공하고 현재 네트워크에서는 실패한다면 라우터 DNS, 기업용 게이트웨이, 포털 인증 또는 방화벽을 우선 점검하세요.
로컬 프록시가 요청을 수신하는지 확인하세요. 업데이트에 127.0.0.1:7890이 필요하다면 커널이 실행 중이고 해당 포트를 실제로 수신 대기하는지 확인하세요. 7890은 흔히 쓰이는 예시일 뿐이므로 현재 설정의 mixed-port 또는 HTTP 프록시 포트를 기준으로 확인해야 합니다.
한 번에 하나씩만 변경하세요. 직접 연결 업데이트와 정상 작동하는 프록시를 통한 업데이트를 각각 테스트하고 결과를 기록하세요. DNS를 바꾸거나 TUN을 켜고 규칙까지 수정하는 등 여러 항목을 동시에 변경하면 원인을 파악하기 어렵습니다.

connection refused는 대상 포트에서 수신 중인 프로세스가 없을 때 흔히 나타납니다. i/o timeout은 연결 단계나 데이터 수신 단계에서 발생할 수 있습니다. 두 오류 모두 로그의 대상 주소와 함께 판단해야 합니다. 대상이 로컬 프록시 포트라면 먼저 로컬 서비스를 점검하고, 구독 서버라면 외부 네트워크 경로를 확인하세요.

User-Agent 제한과 구독 출력 형식

User-Agent는 HTTP 요청 헤더입니다. 구독 서비스는 이를 바탕으로 클라이언트를 구분해 전체 Clash 설정, 노드 목록만 포함된 응답 또는 다른 형식을 반환할 수 있습니다. 브라우저와 클라이언트가 같은 주소에 요청해도 서로 다른 내용을 받는 것은 드문 일이 아닙니다. 일부 서비스는 링크 매개변수에 대상 형식을 명시하도록 요구하므로 요청 헤더만 바꿔서는 해결되지 않을 수 있습니다.

YAML만 수정하지 말고 요청을 보내는 쪽을 확인하세요

클라이언트에 ‘구독 User-Agent’ 옵션이 있다면 서비스 제공업체의 안내에 따라 입력하고 기존 값도 기록해 두세요. 관련 없는 클라이언트로 임의로 위장하지 마세요. 서비스에서 호환되지 않는 필드를 반환할 수 있습니다. 전체 설정을 처음 다운로드하는 과정은 YAML 파싱 전에 이루어지므로 해당 YAML에 요청 헤더 필드를 추가해도 이번 다운로드 요청에는 대개 영향을 주지 않습니다.

mihomo의 proxy-providers는 해당 필드를 지원하는 버전에서 제공자 요청 매개변수를 설정할 수 있습니다. 하지만 이는 커널이 노드 제공자를 가져올 때 쓰는 설정으로, 그래픽 클라이언트가 구독 전체를 업데이트하는 경로와는 다릅니다. 업데이트에 실패하면 로그가 구독 설정을 가리키는지 특정 provider를 가리키는지 먼저 확인하세요.

응답 데이터의 종류 확인

응답 내용	사용 위치	흔한 잘못된 사용
`proxies`, `proxy-groups`, `rules`가 포함된 YAML	전체 설정 가져오기	커널이 노드 유형과 필드를 지원하는지 추가로 확인해야 합니다
대개 `proxies`만 포함된 YAML	노드 제공자	전체 설정으로 가져오면 그룹과 라우팅 규칙이 없습니다
`payload` 규칙 모음	규칙 제공자	노드 구독 가져오기 위치에 잘못 추가함
Base64 텍스트 또는 여러 줄로 된 프로토콜 링크	해당 형식을 지원하는 가져오기 또는 변환 기능	YAML 설정 파서에 바로 전달
HTML 또는 JSON 오류 응답	바로 불러올 수 있는 Clash 설정이 아닙니다	서버 안내를 들여쓰기 오류로 오해함

형식을 변환해야 한다면 구독 제공업체가 지원하는 내보내기 방식이나 신뢰할 수 있는 로컬 도구를 우선 사용하세요. 제3자 온라인 변환 서비스는 원본 링크와 노드 인증 정보를 볼 수 있으므로 일반 텍스트 편집기가 아니라 계정에 접근할 수 있는 서비스로 취급해야 합니다.

YAML 파싱 오류: 먼저 본문을 확인하고 그다음 행 번호를 살펴보세요

mapping values are not allowed, did not find expected key 또는 cannot unmarshal 오류가 나타나면 먼저 다운로드한 파일을 로컬 텍스트 편집기로 여세요. 첫 부분이 <!DOCTYPE html>이라면 인증과 네트워크 단계부터 다시 점검해야 합니다. YAML 들여쓰기를 계속 수정해도 해결되지 않습니다.

들여쓰기, 자료형, 참조를 차례로 확인하세요

들여쓰기: 탭 대신 공백을 사용하고 같은 단계의 들여쓰기를 일관되게 유지하세요. 표시된 오류 행은 파서가 더 이상 진행하지 못한 위치일 수 있으며, 실제 문제는 바로 앞 행에 있을 수 있습니다.
콜론과 따옴표: 이름에 ‘콜론 뒤 공백’이 들어가면 따옴표로 감싸세요. 예: name: "香港: 01". YAML 따옴표 대신 둥근 한국어 인용 부호를 사용하지 마세요.
필드 자료형: 포트는 보통 숫자로 지정하고 불리언 값은 true 또는 false로 작성합니다. proxies, rules 같은 목록은 하이픈 구조를 올바르게 사용해야 합니다.
중복 키: 같은 단계에 dns:나 rules:를 두 번 작성하지 마세요. 파서마다 중복 키를 처리하는 방식이 다를 수 있으므로 먼저 합친 다음 검증하세요.
이름 참조: 정책 그룹에서 참조하는 노드와 규칙에서 지정한 정책 그룹이 실제로 존재하고 이름도 일치해야 합니다. 구독 업데이트 후 노드 이름이 바뀌면 기존에 수동으로 지정한 참조가 더 이상 유효하지 않을 수 있습니다.

아래 설정은 로컬 파싱 및 로드 과정을 확인하기 위한 것으로, 모든 연결은 직접 연결이며 원격 노드는 포함하지 않습니다. 별도의 테스트 파일로 저장하고 기존 구독을 덮어쓰지 마세요.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: "출구 선택"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,출구 선택

이 예시는 통과하지만 구독 설정은 통과하지 못한다면 구독 내용, 병합 스크립트 또는 필드 호환성 문제일 가능성이 높습니다. 외부 구독 주소에 접속할 수 있음을 증명하거나 프록시 노드 연결을 테스트하는 용도로는 사용할 수 없습니다. 포트 사용 중 오류가 표시되면 실행 중인 기존 인스턴스를 종료하거나 사용하지 않는 포트로 바꿔서 불러오세요.

mihomo 명령줄을 사용할 때는 별도 디렉터리에서 아래 설정 검사를 실행할 수 있습니다. subscription-test.yaml은 방금 저장한 테스트 파일을 가리킵니다. 설정에 원격 제공자가 포함되어 있으면 검사 과정에서도 파일 또는 네트워크에 의존할 수 있으므로 순수한 YAML 문법 검사만 수행하는 것은 아닙니다.

mihomo -t -f subscription-test.yaml

커널 비호환, 설정 병합, 업데이트 후 로드 실패

YAML 파싱에 성공해도 커널에서 사용할 수 있다는 뜻은 아닙니다. 구독에 포함된 노드 프로토콜, 전송 옵션, 규칙 유형이 현재 커널에서 지원되지 않을 수 있습니다. unsupported proxy type이나 알 수 없는 규칙 유형이 표시되면 먼저 클라이언트의 ‘정보’ 또는 커널 정보 화면에서 실제 버전을 확인한 뒤 해당 커널 문서와 대조하세요. 앱 버전과 커널 버전은 별도로 확인해야 합니다.

원본 설정, 추가 설정, 실행 설정을 나눠 원인을 찾으세요

구독에서 다운로드한 원본 파일을 보관하고, 호환되는 커널에서 검사를 통과하는지 확인하세요.
해당 설정에 연결된 덮어쓰기, 병합 또는 스크립트 기능을 잠시 비활성화하세요. 구체적인 메뉴 위치는 클라이언트의 설정 편집 화면을 확인하세요.
원본 파일이 정상이라면 로컬 확장 기능을 하나씩 다시 활성화하면서 proxy-groups, rules 또는 제공자 이름이 덮어써지는지 확인하세요.
provider에서 오류가 발생했다면 해당 provider의 url, 저장 경로, 응답 구조, 업데이트 로그를 확인하세요. 최상위 설정만 새로고침해서는 해결되지 않을 수 있습니다.

오류를 없애려고 알 수 없는 필드를 모두 삭제하지 마세요. 일부 필드는 프로토콜 핸드셰이크나 전송 방식을 결정하므로 삭제 후 설정을 불러오는 데 성공해도 노드에 연결하지 못할 수 있습니다. 제공업체가 공식 지원하는 형식을 선택하거나 해당 설정을 처리할 수 있는 유지 관리 중인 클라이언트와 커널을 사용하세요.

업데이트 복구 후 확인 및 문의 준비

문제를 해결한 뒤 수동 업데이트를 한 번 실행하고 업데이트 시각, 노드 수, 커널 로드 로그를 확인하세요. 노드 수가 정상인 것은 첫 번째 확인 단계일 뿐입니다. 노드를 하나 선택해 자주 이용하는 사이트에 접속하고 연결 기록의 정책 그룹과 출구가 예상대로인지 확인하세요. 지연 시간 테스트에 성공해도 모든 트래픽이 정상이라는 뜻은 아니며, 규칙 오류로 특정 도메인이 잘못된 출구를 사용할 수 있습니다.

다운로드 성공: 로그에 HTTP, DNS 또는 TLS 오류가 없고, 웹페이지가 아닌 예상한 형식의 응답을 받았습니다.
파싱 성공: YAML 행 번호 오류, 필드 자료형 오류, 누락된 참조가 없습니다.
로드 성공: 현재 실행 중인 설정이 업데이트된 내용으로 실제 전환되었으며, 커널이 이전 설정으로 되돌아가거나 계속 사용하지 않습니다.
실제 연결 성공: 새 연결 기록을 확인하고 적용된 규칙과 정책 그룹을 점검하세요. 캐시된 페이지의 표시만으로 판단하지 마세요.

필요한 정보를 제공하되 접근 자격 증명은 숨기세요

클라이언트 유지관리자나 구독 제공업체에 문의할 때 운영체제, 클라이언트 버전, 커널 버전, 오류 발생 시각, HTTP 상태 코드, 관련 로그 일부를 첨부하세요. 직접 연결과 프록시를 통한 업데이트 결과, 현재 네트워크와 핫스팟 테스트 결과의 차이도 함께 설명하세요. 스크린샷을 공유하기 전에 전체 구독 링크, 토큰, 노드 비밀번호, 계정 정보를 가리세요. 도메인만 가리고 쿼리 매개변수를 남겨도 인증 정보가 노출될 수 있습니다.

점검 순서는 링크와 인증 확인, 응답 내용과 네트워크 경로 점검, 형식·YAML·커널 호환성 확인, 마지막으로 로컬 덮어쓰기 확인으로 정리할 수 있습니다. 한 번에 한 항목만 변경하고 전후 결과를 기록하면 클라이언트를 반복해서 재설치하는 것보다 구독 업데이트 실패 지점을 더 쉽게 찾을 수 있습니다.