Clash 구독 업데이트 실패·설정 파싱 오류 해결법
구독 URL 만료, 잘못된 응답 형식, YAML 들여쓰기 오류, 코어의 새 필드 미지원 등을 요청부터 설정 로드까지 순서대로 점검하고 로그 오류의 의미를 설명합니다.
먼저 실패 단계 파악하기: 요청, 파싱, 설정 로드
‘구독 업데이트 실패’는 클라이언트가 표시하는 종합 결과일 뿐, 구독 URL이 만료됐다는 뜻은 아닙니다. 업데이트는 보통 구독 URL 요청, 응답 수신, 설정 파싱, 오버라이드 적용, 코어 로드 순서로 진행됩니다. 전체 설정이 원격 노드 목록이나 규칙 목록을 참조한다면 해당 리소스도 별도로 다운로드됩니다.
문제를 확인할 때는 현재 작동하는 설정을 먼저 보존하세요. 모든 구독을 삭제하거나 시스템 프록시, TUN 모드, DNS를 연달아 바꾸지 마세요. 한 번에 조건 하나만 변경하고 업데이트 시간과 관련 로그를 기록해야 실패 단계를 파악할 수 있습니다.
- 백업: ‘구독’ 또는 ‘설정’ 페이지에서 현재 설정을 내보내세요. 로컬 오버라이드, 스크립트, 규칙도 따로 저장합니다. 내보낸 파일에 노드 인증 정보가 포함될 수 있으므로 접근이 제한된 폴더에 보관하세요.
- 재현: ‘로그’를 열고 일시적으로
info수준을 선택한 다음 수동으로 한 번 업데이트해 같은 시간대의 오류를 기록하세요. 정보가 부족할 때만 일시적으로debug를 사용합니다. - 분류: 먼저 HTTP 상태 코드나 네트워크 오류가 있는지 확인하고, 다음으로 YAML 오류 행 번호를 살펴보세요. 마지막으로 프록시 그룹, 규칙, 필드 관련 오류를 확인합니다.
- 기록: 클라이언트 버전, 실제 코어 이름과 코어 버전을 기록하세요. 클라이언트 버전과 mihomo 버전은 다릅니다. 명령줄에서는
mihomo -v로 해당 실행 파일의 버전을 확인할 수 있습니다.
구독 요청 실패: URL과 HTTP 응답부터 확인
상태 코드별 의미와 다음 조치
서비스 제공업체 계정 페이지에서 구독 URL 전체를 다시 복사하세요. 매개변수를 직접 조합하지 마세요. URL의 토큰, 쿼리 매개변수, 경로에 따라 결과가 달라질 수 있습니다. 메신저에서 줄바꿈이 들어가거나 복사할 때 공백이 포함되는 경우, &를 &로 잘못 입력하는 경우에도 다른 리소스를 가리킬 수 있습니다.
| 응답 또는 로그 | 일반적인 의미 | 확인 순서 |
|---|---|---|
401 / 403 | 인증 실패, 토큰 만료 또는 접근 정책에 따른 거부 | 계정 상태를 확인하고 새 URL을 발급받은 다음 기기 및 클라이언트 제한을 확인하세요. 403은 게이트웨이나 보안 페이지에서 반환될 수도 있습니다. |
404 / 410 | 경로가 없거나 리소스가 삭제됨 | 계정 페이지에서 새 URL을 가져오세요. 기존 URL의 도메인만 바꾸지 마세요. |
429 | 요청 빈도 제한 | 반복해서 요청하지 말고 Retry-After 헤더나 서버 안내에 따라 기다린 뒤 다시 시도하세요. |
500 / 502 / 503 | 서버 또는 상위 서버 오류 | 기존 설정을 보존하고 잠시 후 다시 시도하세요. 서비스 제공업체의 공지도 확인합니다. |
200 응답인데 파싱 실패 | 응답은 받았지만 내용이 설정이라고 단정할 수 없음 | 본문이 로그인 페이지, 인증 페이지, 오류 JSON 또는 다른 형식의 구독 데이터인지 확인하세요. |
브라우저에서 열려도 클라이언트 업데이트가 되는 것은 아닙니다
브라우저는 로그인 쿠키를 전송하거나 웹 인증을 완료할 수 있으며, 확장 프로그램을 통해 다른 프록시 경로를 사용할 수도 있습니다. 반면 클라이언트의 구독 요청에는 이런 조건이 없는 경우가 많습니다. 따라서 웹페이지가 열린다고 해서 클라이언트가 구독 API에 접근할 수 있는 것은 아닙니다. 301 또는 302 응답이 있다면 리디렉션 대상이 로그인 페이지가 아니라 구독 리소스인지 확인하세요.
원본 응답을 확인해야 한다면 macOS 또는 Linux의 Bash 터미널에서 아래 명령을 사용하세요. URL이 명령 기록에 그대로 저장되지 않으며 리디렉션도 자동으로 따라가지 않습니다. 먼저 응답 헤더를 확인한 뒤 리디렉션 URL에 접속할지 판단하세요. 이 명령은 직결 경로를 진단하기 위한 것이며 모든 클라이언트가 직결로 업데이트한다는 뜻은 아닙니다.
read -r -s -p '구독 URL: ' SUB_URL
printf '\n'
curl --noproxy '*' \
--connect-timeout 10 \
--max-time 30 \
--dump-header response.headers \
--output response.body \
--write-out 'HTTP %{http_code}\n' \
"$SUB_URL"
unset SUB_URLresponse.headers와 response.body에는 민감한 정보가 포함될 수 있습니다. 로컬에서만 확인하고 진단이 끝나면 삭제하세요. 구독 URL을 공개 변환 사이트에 붙여 넣거나 전체 응답을 공개 온라인 YAML 검사 도구에 전달하지 마세요.
네트워크 및 TLS 오류: 직결과 프록시 경로를 나눠 테스트
HTTP 응답을 받지 못했다면 먼저 네트워크 연결을 해결해야 합니다. 시스템 프록시는 시스템 프록시 설정을 따르는 요청에만 영향을 줍니다. 클라이언트의 구독 다운로드는 자체 다운로드 기능을 사용할 수 있습니다. TUN 모드는 일부 트래픽의 경로를 바꾸지만, 만료된 토큰이나 잘못된 응답 형식, YAML 문법 오류를 해결하지는 못합니다.
no such host: 도메인 이름을 확인할 수 없습니다. 구독 도메인의 철자를 확인하고 시스템 DNS와 클라이언트 DNS 로그를 점검하세요. 이름 확인 실패를 노드 프로토콜 오류로 오인하지 마세요.connection refused: 대상 주소에서 연결을 거부했습니다. 로그에127.0.0.1:7890이 표시된다면 구독을 바꾸기 전에 로컬 프록시가 해당 포트에서 연결을 수신 중인지 확인하세요.i/o timeout,context deadline exceeded: 연결, TLS 또는 응답 수신 시간 초과입니다. 클라이언트에서 제공하는 직결 업데이트와 프록시 업데이트를 각각 한 번씩만 시도하고 결과를 기록하세요.x509, 인증서 만료 또는 호스트 이름 불일치: 시스템 날짜, 시간 동기화, 구독 도메인과 네트워크의 HTTPS 검사 소프트웨어를 확인하세요. 인증서 검증을 끄는 방식으로 문제를 덮지 마세요.
업데이트에 프록시가 필요한데 현재 구독을 불러올 수 없다면 시작 단계에서 의존성 문제가 생길 수 있습니다. 사용할 노드가 없어 대체 설정을 다운로드하지 못하는 상황입니다. 이때는 이전에 저장한 작동 가능한 설정으로 되돌린 뒤 프록시 업데이트를 시도하거나, 서비스에서 허용한다면 접근 가능한 직결 주소를 사용하세요. 클라이언트 데이터를 계속 초기화하는 것보다 기존 설정을 보존하는 편이 복구에 유리합니다.
잘못된 응답 형식: 전체 설정과 노드 목록 구분하기
HTTP 200은 요청이 성공했다는 뜻일 뿐, 현재 가져오기 메뉴에서 사용할 수 있는 내용이라는 보장은 없습니다. 로컬 텍스트 편집기로 응답의 시작 부분과 최상위 필드를 확인하고 서비스 제공업체가 안내한 형식과 비교하세요. 파일 확장자만 보고 판단하지 마세요.
| 응답 특징 | 가능한 내용 | 조치 |
|---|---|---|
<!DOCTYPE html> 또는 <html | 로그인 페이지, 인증 페이지 또는 웹 오류 메시지 | 실제 구독 API 주소를 확인하세요. 웹페이지를 YAML 파일로 저장해 가져오지 마세요. |
| 긴 인코딩 문자열 또는 한 줄씩 나열된 프로토콜 URL | 다른 클라이언트용 노드 구독 | 계정 페이지에서 Clash 또는 서비스가 안내하는 mihomo 호환 형식을 선택하세요. |
proxies: 노드 목록만 있음 | 노드 목록 파일일 수 있음 | 전체 설정으로 바로 활성화하는 대신 proxy-providers에서 참조해야 하는지 확인하세요. |
proxy-groups:, rules: 등의 필드가 포함됨 | 전체 설정일 수 있음 | 문법, 참조 관계, 코어 호환성을 계속 확인하세요. 필드가 있다는 이유만으로 실행할 수 있다고 판단하지 마세요. |
기본 설정은 로드되지만 로그의 실패 URL이 proxy-providers 또는 rule-providers에 속한다면 문제는 참조된 리소스에 있을 수 있으며 기본 구독과는 무관할 수 있습니다. 노드 목록과 규칙 목록은 데이터 구조도 서로 다릅니다. 해당 provider의 url, format, behavior와 실제 응답을 확인해 규칙 목록을 노드 목록으로 파싱하지 않도록 하세요.
YAML 파싱 오류: 행 번호를 기준으로 들여쓰기와 데이터 유형 확인
yaml: line …, did not find expected key, cannot unmarshal은 대체로 텍스트 구조나 데이터 유형 문제를 나타냅니다. 로그에 표시된 행 번호는 파서가 이상을 발견한 위치인 경우가 많습니다. 실제 오류는 바로 앞 행에 있을 수도 있습니다. 예를 들어 따옴표를 닫지 않았거나 목록 단계가 잘못됐거나 콜론 뒤에 공백이 빠진 경우입니다.
먼저 확인할 네 가지 항목
- 들여쓰기: 탭 대신 공백을 사용하세요. 각 단계에 공백 2개를 쓰는 방식이 일반적이지만 YAML에서 허용되는 유일한 폭은 아닙니다. 같은 단계의 필드는 들여쓰기를 맞춰야 합니다.
- 문장부호: 필드에는 반각 콜론을 사용하고 키와 값 사이에 공백을 넣으세요. 설정 문법에 전각 콜론이나 굽은 따옴표를 복사하지 마세요.
- 데이터 유형: 포트는 보통
7890처럼 정수로 입력합니다. 불리언 값은true또는false로 쓰고 목록 항목은-로 시작합니다. 목록 전체를 문자열로 쓰면 유형 오류가 발생할 수 있습니다. - 이름과 특수 문자: 이름에
:이나#같은 문자열이 있으면 따옴표로 올바르게 감싸세요. 정책 그룹에서 이름을 참조할 때는 공백, 대소문자, 기호까지 정확히 일치해야 합니다.
아래는 문제를 분리해 확인하기 위한 직결 설정이며 구독 노드는 포함하지 않습니다. 기본 YAML을 로컬 코어가 읽을 수 있는지 확인하는 용도일 뿐 프록시 연결을 테스트하지는 않습니다. 7890 포트가 이미 사용 중이라면 해당 프로그램을 종료하거나 테스트용 복사본에서 사용 가능한 포트를 선택하세요.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT설정을 UTF-8 텍스트 파일인 profile.yaml로 저장하세요. mihomo에서는 아래 명령으로 설정을 테스트할 수 있습니다. Windows PowerShell에서 실행 파일이 현재 폴더에 있다면 .\mihomo.exe -t -f .\profile.yaml을 사용할 수 있습니다.
mihomo -v
mihomo -t -f ./profile.yaml테스트에는 클라이언트에서 실제로 실행 중인 것과 동일한 코어와 작업 디렉터리를 사용하는 것이 좋습니다. 원격 provider나 상대 경로가 포함된 경우 네트워크, 캐시, 파일 경로의 영향을 받을 수도 있습니다. 테스트 통과는 이번 설정 검사에서 차단 요소를 찾지 못했다는 뜻일 뿐, 모든 노드와 DNS, 규칙 다운로드가 정상임을 보장하지 않습니다.
문법은 통과했지만 로드되지 않을 때: 코어, 오버라이드, 참조 확인
클라이언트 이름만으로 코어 호환성을 판단할 수 없습니다
기존 Clash와 Clash Meta(현재 mihomo로 불림)는 지원 범위가 다릅니다. 프로토콜, 전송 매개변수, 규칙 필드 지원 여부도 버전에 따라 달라집니다. unsupported proxy type 오류가 표시되면 먼저 해당 노드 유형과 실제 실행 중인 코어를 확인하세요. 파일 이름을 .yaml로 바꿔도 프로토콜 지원이 추가되지는 않습니다.
알 수 없는 필드의 처리 방식은 코어 버전과 설정 위치에 따라 다릅니다. 무시되는 필드도 있고 오류를 일으키는 필드도 있습니다. 따라서 ‘가져오기 성공’만으로 새 필드가 적용됐다고 볼 수 없습니다. 우선 서비스 제공업체가 안내한 호환 형식을 사용하고 코어 릴리스 노트를 확인해 업데이트 여부를 결정하세요. 인식할 수 없는 필드를 무작정 삭제하지 마세요.
오류 대상에 따라 의존 항목 확인
proxy … not found: 정책 그룹이나 규칙이 참조하는 대상 이름을 확인하세요. 구독 업데이트 후 노드 이름이 바뀌었는데 로컬 오버라이드가 이전 이름을 참조하면 참조 오류가 발생할 수 있습니다.- provider를 찾을 수 없음:
use:참조가proxy-providers의 키 이름과 일치하는지 확인하고 병합 과정에서 provider 정의 전체가 덮어쓰이지 않았는지도 확인하세요. - 규칙 대상이 없음: 규칙 끝에 지정된 정책 이름과 프록시 그룹 이름을 확인하세요. 규칙에서 참조하는 그룹은 이름까지 완전히 일치해야 합니다. 비슷한 이름의 그룹만 있는 것으로는 충분하지 않습니다.
address already in use: 구독 형식 오류가 아니라 실행 중인 포트 충돌일 가능성이 큽니다. 혼합 포트, DNS 수신 포트, 제어 인터페이스 포트가 다른 프로세스와 충돌하는지 확인하세요.
다운로드한 원본 설정은 테스트를 통과하지만 클라이언트에서 활성화한 뒤 오류가 난다면 ‘오버라이드’, ‘병합’, ‘스크립트’ 기능을 중점적으로 확인하세요. 먼저 내보낸 뒤 일시적으로 비활성화하고 가공하지 않은 설정을 한 번 테스트한 다음 하나씩 다시 활성화합니다. 특히 스크립트가 노드 이름을 바꾸거나 proxy-groups를 덮어쓰거나 존재하지 않는 규칙 대상을 추가하는지 살펴보세요.
업데이트 복구 후 확인 및 문의 체크리스트
오류 메시지가 사라진 뒤 전체 과정을 다시 확인하세요. ‘업데이트 성공’만 보면 provider 다운로드 실패나 빈 프록시 그룹을 놓칠 수 있습니다. 웹페이지가 열린다고 해도 트래픽이 직결 규칙을 사용한 결과일 수 있습니다.
- 구독 업데이트 시간이 변경됐는지 확인하고 노드 수, 정책 그룹, 규칙이 예상대로인지 점검하세요.
- 대상 설정을 활성화하고 같은 시간대의 로그를 확인해 새로운 설정 로드 오류나 provider 업데이트 오류가 없는지 확인하세요.
- ‘연결’ 페이지에서 대상에 접속을 시도하고 일치한 규칙, 아웃바운드 정책, 노드 이름을 확인해 실제 경로를 파악하세요.
- 일시적으로 비활성화한 오버라이드나 스크립트를 복원하고 항목을 하나씩 복원할 때마다 다시 확인하세요. 마지막으로 로그 수준을 평소 설정으로 되돌립니다.
클라이언트 유지관리자나 구독 서비스 제공업체에 문의할 때는 클라이언트 버전, 코어 버전, 운영체제, 업데이트 시간, HTTP 상태 코드, 민감 정보를 제거한 전체 오류 행을 제공하세요. 설정 일부를 첨부할 때는 관련 들여쓰기와 참조 관계를 유지하되 구독 토큰, 비밀번호, 개인 키, 노드 서버 주소는 삭제해야 합니다. 특정 버전으로 업그레이드한 뒤에만 문제가 발생했다면 업그레이드 전후 버전도 함께 적으세요.
문제 해결 순서는 요청 도달 여부 확인, 응답 형식 확인, YAML 문법과 코어 호환성 점검, 오버라이드와 실행 환경 확인으로 정리할 수 있습니다. 각 단계에서 확인된 증거에 해당하는 문제만 처리하면 포트, DNS, TUN을 한꺼번에 바꾸는 것보다 원인을 찾기 쉽습니다. 설치와 설정 절차를 다시 확인하려면 클라이언트 가이드를, 용어와 사용법을 확인하려면 자주 묻는 질문을 참고하세요.